Changes between Initial Version and Version 1 of Ticket #37212, comment 4


Ignore:
Timestamp:
Jul 15, 2026, 2:21:44 PM (2 weeks ago)
Author:
Mike Edmunds

Legend:

Unmodified
Added
Removed
Modified

  • Ticket #37212, comment 4

    initial v1  
     1Also…
     2
     3== 4. Inconsistent handling of versionchanged, versionadded, deprecated directives
     4
     5The djangodocs extension implements custom `.. versionadded::` and `.. versionchanged::` directives and overrides Sphinx's `visit_versionmodified()` in html writers (which also applies to `.. deprecated::` and `.. versionremoved::`). There seem to be three goals:
     6
     7a. Show "Django N.M" rather than the generic "version N.M" in these messages.
     8b. Show "Added in Django Development version" rather than "Added in Django N.M" for the current in-development version (as set by conf.py `django_next_version`).
     9c. Wrap the changeset message in a `<span class="title">` so it can be bolded. (This seems to be an obsolete workaround for a very early version of Sphinx's html generation.)
     10
     11There are multiple problems with the current implementation:
     12
     13* The DOM generated by `versionadded` and `versionchanged` is significantly different from that for `deprecated` (which goes through Sphinx's native `domains.changeset.VersionModified` directive, and outputs a `<span class="versionmodified">` for ''all'' changeset directives). This results in inconsistent styling with third-party themes.
     14* Item b is applied only in html-based output formats. Other formats will use Sphinx's standard changeset messages.
     15* None of this applies to `deprecated`, so you will see "Deprecated since version 6.2" rather than "Deprecated since Django development version" (in the [https://docs.djangoproject.com/en/dev/ref/request-response/#serializing-non-dictionary-objects current 6.2 dev build]).
     16* Sphinx 9.0 renamed all these directives to `version-changed`, `version-deprecated`, etc. The original names are still supported as aliases. Django's custom handling would not apply to any uses of the new, hyphenated changeset directive names. (And we don't have a linter to prohibit the new names.)
     17
     18Also, the capitalization seems wrong—it should be "Added in Django development version" not "Added in Django Development version." And there's no handling for `versionremoved` (though Django's docs don't use that). And it doesn't support localized message strings (but djangoproject.com handles localization through a different mechanism, so this doesn't really matter).
     19
     20I think a better approach here would be to subclass Sphinx's native `VersionModified` to replace the `django_next_version` string while retaining all standard behavior; update Sphinx's changeset label strings to use "Django" rather than "version" in all output formats; and let Sphinx generate consistent HTML for all changeset directives.
     21
     22Compatibility note: nothing I can find actually relies on the `<span class="title">`. djangoproject.com has [https://github.com/django/djangoproject.com/blob/b1fe4eccf0f6eb69d9c742e0c82ee9b7b1329419/djangoproject/scss/_style.scss#L2565-L2584 rules targeting other changeset classes], and even the local theme's djangodocs.css targets the `span.versionmodified` present in Sphinx's normal changeset directive output. Changing to Sphinx's native behavior should not break any styles.
Back to Top