autodoc: change :novalue: to :annoation: option

The :novalue: option is now called :annotation: and has an additional feature:
When given with an argument, you can specify what the annotation
of the object will be.

3 files changed, 39 insertions, 10 deletions

diff --git a/doc/ext/autodoc.rst b/doc/ext/autodoc.rst
index 11fd3c8d..4f16723d 100644
--- a/doc/ext/autodoc.rst
+++ b/doc/ext/autodoc.rst
@@ -201,10 +201,19 @@ inserting them into the page source under a suitable :rst:dir:`py:module`,
    but do not offer the options used for automatic member documentation.
 
    :rst:dir:`autodata` and :rst:dir:`autoattribute` support
-   the ``novalue`` option. No value will be parsed from the code::
+   the ``annotation`` option.
+   Without this option, the representation of the object
+   will be shown in the documentation.
+   When the option is given without arguments,
+   only the name of the object will be printed::
 
       .. autodata:: CD_DRIVE
-         :novalue:
+         :annotation:
+
+   You can tell sphinx what should be printed after the name::
+
+      .. autodata:: CD_DRIVE
+         :annotation: = your CD device name
 
    For module data members and class attributes, documentation can either be put
    into a comment with special formatting (using a ``#:`` to start the comment
@@ -241,7 +250,8 @@ inserting them into the page source under a suitable :rst:dir:`py:module`,
       Comment docs are now allowed on the same line after an assignment.
 
    .. versionchanged:: 1.2
-      :rst:dir:`autodata` and :rst:dir:`autoattribute` have a ``novalue`` option
+      :rst:dir:`autodata` and :rst:dir:`autoattribute` have
+      an ``annotation`` option
 
    .. note::
 
diff --git a/sphinx/ext/autodoc.py b/sphinx/ext/autodoc.py
index 2bdba7e4..07758e3c 100644
--- a/sphinx/ext/autodoc.py
+++ b/sphinx/ext/autodoc.py
@@ -85,6 +85,15 @@ def members_set_option(arg):
         return ALL
     return set(x.strip() for x in arg.split(','))
 
+SUPPRESS = object()
+
+def annotation_option(arg):
+    if arg is None:
+        # suppress showing the representation of the object
+        return SUPPRESS
+    else:
+        return arg
+
 def bool_option(arg):
     """Used to convert flag options to auto directives.  (Instead of
     directives.flag(), which returns None).
@@ -1097,8 +1106,8 @@ class DataDocumenter(ModuleLevelDocumenter):
     objtype = 'data'
     member_order = 40
     priority = -10
-    option_spec = ModuleLevelDocumenter.option_spec
-    option_spec["novalue"] = bool_option
+    option_spec = dict(ModuleLevelDocumenter.option_spec)
+    option_spec["annotation"] = annotation_option
 
     @classmethod
     def can_document_member(cls, member, membername, isattr, parent):
@@ -1106,13 +1115,18 @@ class DataDocumenter(ModuleLevelDocumenter):
 
     def add_directive_header(self, sig):
         ModuleLevelDocumenter.add_directive_header(self, sig)
-        if not self.options.novalue:
+        if not self.options.annotation:
             try:
                 objrepr = safe_repr(self.object)
             except ValueError:
                 pass
             else:
                 self.add_line(u'   :annotation: = ' + objrepr, '<autodoc>')
+        elif self.options.annotation is SUPPRESS:
+            pass
+        else:
+            self.add_line(u'   :annotation: %s' % self.options.annotation,
+                          '<autodoc>')
 
     def document_members(self, all_members=False):
         pass
@@ -1184,8 +1198,8 @@ class AttributeDocumenter(ClassLevelDocumenter):
     """
     objtype = 'attribute'
     member_order = 60
-    option_spec = ModuleLevelDocumenter.option_spec
-    option_spec["novalue"] = bool_option
+    option_spec = dict(ModuleLevelDocumenter.option_spec)
+    option_spec["annotation"] = annotation_option
 
     # must be higher than the MethodDocumenter, else it will recognize
     # some non-data descriptors as methods
@@ -1221,13 +1235,18 @@ class AttributeDocumenter(ClassLevelDocumenter):
 
     def add_directive_header(self, sig):
         ClassLevelDocumenter.add_directive_header(self, sig)
-        if not self._datadescriptor and not self.options.novalue:
+        if not self._datadescriptor and not self.options.annotation:
             try:
                 objrepr = safe_repr(self.object)
             except ValueError:
                 pass
             else:
                 self.add_line(u'   :annotation: = ' + objrepr, '<autodoc>')
+        elif self.options.annotation is SUPPRESS:
+            pass
+        else:
+            self.add_line(u'   :annotation: %s' % self.options.annotation,
+                          '<autodoc>')
 
     def add_content(self, more_content, no_docstring=False):
         if not self._datadescriptor:
diff --git a/tests/test_autodoc.py b/tests/test_autodoc.py
index bef9c338..95eda590 100644
--- a/tests/test_autodoc.py
+++ b/tests/test_autodoc.py
@@ -38,7 +38,7 @@ def setup_module():
         special_members = False,
         show_inheritance = False,
         noindex = False,
-        novalue = False,
+        annotation = None,
         synopsis = '',
         platform = '',
         deprecated = False,