Outdated docs CSS in local and preview builds

[Mike Edmunds]

The CSS used for documentation in local and ReadTheDocs PR preview builds is significantly different from the CSS used on docs.djangoproject.com.

The styles in docs/_theme/djangodocs/static/djangodocs.css:

• have usability problems (​forum discussion)
• are missing semantically-important styles (​forum discussion)
• don't support dark mode

These and other differences complicate contributing to the documentation, as you can't really be sure how it's going to look until the PR is merged and published.

We should find a way to replace docs/_theme/djangodocs/static/*.css with the styles from djangoproject.com. (E.g., the result of make compile-scss-debug in that project.)

[Natalia Bidart]

Makes sense, I agree this is desired. How to accomplish the goal, it's something I don't see clearly but I'm eager to see options!

[Mike Edmunds]

PR: ​https://github.com/django/django/pull/21416

[Mike Edmunds]

Due to concerns about ongoing maintenance for a custom theme (and unclear license status of the djangoproject.com stylesheets), the current proposal is to replace the custom docs/_theme/djangoproject theme with a third-party, well-maintained Sphinx theme such as furo or pydata-sphinx-theme.

See also #37212 and #35874.

[nessita <124304+nessita@…>]

In 9158562:

Fixed #37212 -- Improved djangodocs Sphinx extension portability.

• 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.