Commit 4e25198e authored by Juan Catalano's avatar Juan Catalano Committed by Claude Paroz
Browse files

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.
parent 3be8165b

docs/_ext/djangodocs.py

+10 −6
Original line number Diff line number Diff line
@@ -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:

            inodes, messages = self.state.inline_text(self.arguments[1], self.lineno+1)

            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

+2 −2
Original line number Diff line number Diff line
@@ -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

line comment and a mandatory blank line.

documentation with: "``.. versionadded:: X.Y``", followed by a a mandatory

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