#20104: Make versionchanged directive less prone to mis-use.
-----------------------------------------+------------------------
Reporter: carljm | Owner: nobody
Type: Bug | Status: new
Component: Documentation | Version: 1.5
Severity: Normal | Keywords:
Triage Stage: Accepted | Has patch: 0
Needs documentation: 0 | Needs tests: 0
Patch needs improvement: 0 | Easy pickings: 0
UI/UX: 0 |
-----------------------------------------+------------------------
When the versionchanged directive is used like this:
{{{
.. versionchanged:: 1.6
Here is some text.
}}}
This is a directive with two arguments, and it is rendered in the docs as
"Changed in Django 1.5: Here is some text."
When it is used like this:
{{{
.. versionchanged:: 1.6
Here is some text.
}}}
This is a directive with one argument, and content. It is rendered in the
docs as "Changed in Django 1.5." The content is entirely ignored.
And in our docs, we often use it like this:
{{{
.. versionchanged:: 1.6
Here is some text.
}}}
This is a directive with one argument and no content, followed by a new
paragraph which is unrelated to the directive (as far as Sphinx is
concerned). This usage "works" (the following paragraph is rendered) but
frequently leads to ambiguity about exactly how much of the following text
is intended to be covered by the versionchanged declaration.
The reason for the content loss in the second case is that the
versionchanged directive code checks `if len(self.arguments) == 2` and if
not, ignores the content too. Obviously, this behavior is a foot-gun for
documentation authors. We have at least one case I've found in the docs (I
would bet there are more) where the directive is used in the second form,
and thus the information about _what_ changed is not rendered in the docs
at all (see
https://github.com/django/django/blob/aaec4f2bd8a63b3dceebad7804c5897e7874833d/docs/ref/contrib/gis/geos.txt#L279
and
https://docs.djangoproject.com/en/dev/ref/contrib/gis/geos/#django.contrib.gis.geos.GEOSGeometry.hex).
I think the versionchanged directive should be changed in one of the
following ways to eliminate this footgun:
1) Make it `has_content = False` so Sphinx will error if the second form
is used, rather than silently hiding the content. (Change all instances of
the second form to the first form.)
2) Make it accept content but not a second argument, so that Sphinx will
error if the first form is used. (Change all instances of the first form
to the second form.)
3) Make it accept both a second argument and content. Render the second
argument on the same line as the text "Changed in version 1.6:" (this is
how it is currently rendered), render the content as a boxed paragraph
(like a note or warning).
I think that (3) is over-engineered, and (1) is atypical - most Sphinx
directives that accept arbitrary text take this text as content rather
than an argument (which allows Sphinx inline formatting to be applied in
the content). So I favor (2).
In any case, I think that instances of the third form should be changed to
one of the first two forms, to reduce ambiguity.
--
Ticket URL: <https://code.djangoproject.com/ticket/20104>
Django <https://code.djangoproject.com/>
The Web framework for perfectionists with deadlines.
--
You received this message because you are subscribed to the Google Groups
"Django updates" group.
To unsubscribe from this group and stop receiving emails from it, send an email
to [email protected].
To post to this group, send email to [email protected].
For more options, visit https://groups.google.com/groups/opt_out.
