Fixed #20104 -- Changed VersionDirective in order to avoid ambiguity.

As explained in ticket #20104, the use of versionchanged/versionadded
was confusing.

To solve this ambiguity these directives no longer accept a second
argument but now they only receive the version number (1st arg) and then
a content with the proper comment.

docs/_ext/djangodocs.py

@@ -64,21 +64,25 @@ class VersionDirective(Directive):
     option_spec = {}
 
     def run(self):
+        if len(self.arguments) > 1:
+            msg = """Only one argument accepted for directive '{directive_name}::'.
+            Comments should be provided as content,
+            not as an extra argument.""".format(directive_name=self.name)
+            raise ValueError(msg)
+
         env = self.state.document.settings.env
         ret = []
         node = addnodes.versionmodified()
         ret.append(node)
+
         if self.arguments[0] == env.config.django_next_version:
             node['version'] = "Development version"
         else:
             node['version'] = self.arguments[0]
+
         node['type'] = self.name
-        if len(self.arguments) == 2:
+        if self.content:
-            inodes, messages = self.state.inline_text(self.arguments[1], self.lineno+1)
+            self.state.nested_parse(self.content, self.content_offset, node)
-            node.extend(inodes)
-            if self.content:
-                self.state.nested_parse(self.content, self.content_offset, node)
-            ret = ret + messages
         env.note_versionchange(node['type'], node['version'], node, self.lineno)
         return ret
 

docs/internals/contributing/writing-documentation.txt

@@ -188,8 +188,8 @@ Our policy for new features is:
     release, not the development version.
 
 Our preferred way for marking new features is by prefacing the features'
-documentation with: "``.. versionadded:: X.Y``", followed by an optional one
+documentation with: "``.. versionadded:: X.Y``", followed by a a mandatory
-line comment and a mandatory blank line.
+blank line and an optional content (indented).
 
 General improvements, or other changes to the APIs that should be emphasized
 should use the "``.. versionchanged:: X.Y``" directive (with the same format