From 4e25198ec298732409217321be10e1e06be2fcbd Mon Sep 17 00:00:00 2001 From: Juan Catalano Date: Sun, 24 Mar 2013 22:48:23 -0700 Subject: [PATCH] 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 | 16 ++++++++++------ .../contributing/writing-documentation.txt | 4 ++-- 2 files changed, 12 insertions(+), 8 deletions(-) diff --git a/docs/_ext/djangodocs.py b/docs/_ext/djangodocs.py index 572bcd2e29..80967580ac 100644 --- a/docs/_ext/djangodocs.py +++ b/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: - 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 + if self.content: + self.state.nested_parse(self.content, self.content_offset, node) env.note_versionchange(node['type'], node['version'], node, self.lineno) return ret diff --git a/docs/internals/contributing/writing-documentation.txt b/docs/internals/contributing/writing-documentation.txt index 469f8614b9..2944dea504 100644 --- a/docs/internals/contributing/writing-documentation.txt +++ b/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 -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