id summary reporter owner description type status component version severity resolution keywords cc stage has_patch needs_docs needs_tests needs_better_patch easy ui_ux 20104 Make versionchanged directive less prone to mis-use. Carl Meyer jcatalan "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." Bug closed Documentation 1.5 Normal fixed Accepted 1 1 0 1 0 0