| Age | Commit message (Collapse) | Author |
|---|
|
Updated docs `make black` and `make lint` checks to use Sphinx's own
source file discovery to get the list of docs source files. This makes
docs/conf.py the single source of truth for which files are/aren't docs
sources. The exclusions were previously duplicated by hand in Makefile,
make.bat, and lint.py, where they could drift from conf.py.
Created a Python blacken-sources.py wrapper around blacken-docs, similar
to the existing lint.py for sphinx-lint. This replaces shell and batch
file commands that tried (only partially successfully) to replicate
Sphinx's source discovery.
Removed `--jobs 0` from the sphinx-lint arguments to allow parallel
linting, since sphinx-lint treats `--jobs 0` as serial instead of
defaulting to `auto`.
Also added Sphinx to the tox environments running the docs checks, since
neither `blacken-docs` nor `sphinx-lint` depends on Sphinx.
Thanks to Natalia Bidart for review and improvements.
|
|
Created an "epubcheck" target in the docs makefiles and docs workflow.
Because EPUBCheck requires a Java runtime, did not include it in the
general "make check" target.
|
|
* Removed unnecessary `table` and `parameterlist` customizations from
the djangodocs Sphinx extension's `DjangoHTMLTranslator`. These were
meant to avoid obsolete html from Docutils' html4 writer (`border=1`
in `<table>` tags and and `<big>` around parameter list parens).
Sphinx 2.0 switched to the html5 writer, which doesn't emit that html.
These overrides are no longer necessary, rely on Sphinx internals that
often break in new versions, and interfere with third-party themes.
* Moved the console-tabs.css stylesheet to docs/_static and removed
logic for conditionally including it only in pages with console tabs.
That depended on custom handling in the djangodocs theme layout.html
template, which isn't portable to other themes.
* Switched console tabs from Font Awesome brand icons to text and
removed the vendored fa-brands fonts (to avoid moving them from the
djangodocs theme to the docs/_static dir).
* Ensured both console tabs include a wrapper div around literal code
blocks: `<div class="highlight-{lexer} notranslate">` (where lexer is
`console` for Unix and `doscon` for Windows). This wrapper had been
missing for the Windows content, which could cause shifting layouts
when changing tabs with third-party Sphinx themes (and may have
interfered with browser translation tools).
Fixed by rendering the Windows tab with a temporary literal block,
matching how the Unix tab is rendered. Removed direct call to the
Pygments highlighter.
The Windows tab is no longer force-highlighted, so a doscon lexing
failure now reports a warning rather than being silently ignored.
* Removed custom `VersionDirective` and HTML writer overrides for
`visit_versionmodified()` and `depart_versionmodified()`. Sphinx's
standard changeset directives are now used. (Refs #20104.)
The original code was meant to substitute "development version" for
conf.py `django_next_version` and to refer to "Django N.M" rather than
the generic "version N.M" in changeset messages. But it missed the
`deprecated` directive and aliases like `version-modified` added in
Sphinx 9.0, didn't apply to non-HTML output formats, and generated
inconsistent HTML that wasn't compatible with standard Sphinx themes.
Related cleanup:
* Updated documentation on using versionadded and versionchanged
directives to accurately reflect Sphinx's rendered text, and removed
the policy bullet describing the old Django-specific phrasing.
* Enabled biome for all css and js files in docs (except in
docs/_build).
* Consistently excluded all non-docs source dirs and requirements.txt
from searches for *.txt source files in conf.py exclude_patterns,
make.bat, Makefile, and lint.py.
Refs #35874, #37138, #20104.
|
|
Changed djangodocs extension to register DjangoHTMLTranslator for any
html-format builder (in the builder-inited hook), rather than a limited
list of builders at startup. That fixes missing content in dirhtml and
standard html builds (including ReadTheDocs PR previews):
- Missing console tabs
- Empty divs for versionadded and versionchanged directives
Removed JS code that depended on jQuery, which hasn't worked since
Sphinx 6.0 dropped jQuery in 2023:
- Unnecessary console tabs click handling. (Console tab behavior is
implemented purely in CSS.)
- Client-side hyperlinking of Django template tags and filters in code
examples. (This is also not supported on docs.djangoproject.com.)
Removed custom DjangoStandaloneHTMLBuilder and "djangohtml" builder
type. Its sole purpose was to generate the "templatebuiltins.js" file
used for the (non-functional) client-side template filter/tag linking.
Changed docs "make html" target from "djangohtml" to standard "html".
|
|
|
|
The `check` docs target now runs spelling, black, and lint, so all
current documentation quality checks can be run with a single command.
Also documented the lint-docs check's availability and usage.
|
|
This adds a `lint.py` script to run sphinx-lint on Django's docs files,
a mathing `lint` target in the `docs/Makefile` and `docs/make.bat`, and
updates `docs/requirements.txt` accordingly.
|
|
Added a new 'check' rule to the docs Makefile which runs both the black
and spelling checks.
|
|
The `make black` target in the docs directory used Linux-specific
syntax for its `find` command. Changed to syntax that also works
on macOS and other BSD Unix variants.
|
|
|
|
|
|
docs.
This adds:
- GitHub actions,
- tox configuration,
- pre-commit hook, and
- makefile rules
to run blacken-docs linter.
Co-authored-by: David Smith <smithdc@gmail.com>
|
|
Empty language is not supported anymore.
|
|
|
|
This is helpful if you build and test documentation updates in
your development env.
Copied from CPython's Doc/Makefile.
|
|
|
|
|
|
|
|
Added -n to sphinx builds to catch issues going forward.
|
|
Thanks orontee for the report and initial patch.
|
|
This have been copied from sphinx-quickstart result in latest sphinx versions.
git-svn-id: http://code.djangoproject.com/svn/django/trunk@17877 bcc190cf-cafb-0310-a4f2-bffc1f526a37
|
|
git-svn-id: http://code.djangoproject.com/svn/django/trunk@13446 bcc190cf-cafb-0310-a4f2-bffc1f526a37
|
|
Implemented in javascript because doing it 'properly' is pretty much impossible with Sphinx and Pygments.
Refs #12249
git-svn-id: http://code.djangoproject.com/svn/django/trunk@13135 bcc190cf-cafb-0310-a4f2-bffc1f526a37
|
|
makefile. Thanks to Alex for the patch.
git-svn-id: http://code.djangoproject.com/svn/django/trunk@13126 bcc190cf-cafb-0310-a4f2-bffc1f526a37
|
|
http://docs.djangoproject.com/.
git-svn-id: http://code.djangoproject.com/svn/django/trunk@8506 bcc190cf-cafb-0310-a4f2-bffc1f526a37
|
|
[http://sphinx.pocoo.org/ Sphinx]. If you've got Sphinx installed (the latest version) along with [http://docutils.sf.net docutils], you should be able to easily build the docs locally using {{{sphinx-build}}} or the included {{{Makefile}}}. This use a basic (and pretty crappy) index for the documentation and the built-in Sphinx styles (which are actually quite nice).
git-svn-id: http://code.djangoproject.com/svn/django/trunk@7370 bcc190cf-cafb-0310-a4f2-bffc1f526a37
|
