From 6b9f35455ddadfe519289ed6867a9798ba40918a Mon Sep 17 00:00:00 2001 From: Johannes Dewender Date: Tue, 22 Jan 2013 17:58:45 +0100 Subject: [PATCH 1/4] autodoc: novalue option for autodata and autoattribute This adds a ":novalue:" option to "autodata" and "autoattribute" from the autodoc extension. When the option is set, no value will be in the output. --- sphinx/ext/autodoc.py | 19 ++++++++++++------- 1 file changed, 12 insertions(+), 7 deletions(-) diff --git a/sphinx/ext/autodoc.py b/sphinx/ext/autodoc.py index 45dbdcdb4..4181818bc 100644 --- a/sphinx/ext/autodoc.py +++ b/sphinx/ext/autodoc.py @@ -1097,6 +1097,8 @@ class DataDocumenter(ModuleLevelDocumenter): objtype = 'data' member_order = 40 priority = -10 + option_spec = ModuleLevelDocumenter.option_spec + option_spec["novalue"] = bool_option @classmethod def can_document_member(cls, member, membername, isattr, parent): @@ -1104,12 +1106,13 @@ class DataDocumenter(ModuleLevelDocumenter): def add_directive_header(self, sig): ModuleLevelDocumenter.add_directive_header(self, sig) - try: - objrepr = safe_repr(self.object) - except ValueError: - pass - else: - self.add_line(u' :annotation: = ' + objrepr, '') + if not "novalue" in self.options: + try: + objrepr = safe_repr(self.object) + except ValueError: + pass + else: + self.add_line(u' :annotation: = ' + objrepr, '') def document_members(self, all_members=False): pass @@ -1181,6 +1184,8 @@ class AttributeDocumenter(ClassLevelDocumenter): """ objtype = 'attribute' member_order = 60 + option_spec = ModuleLevelDocumenter.option_spec + option_spec["novalue"] = bool_option # must be higher than the MethodDocumenter, else it will recognize # some non-data descriptors as methods @@ -1216,7 +1221,7 @@ class AttributeDocumenter(ClassLevelDocumenter): def add_directive_header(self, sig): ClassLevelDocumenter.add_directive_header(self, sig) - if not self._datadescriptor: + if not self._datadescriptor or "novalue" in self.options: try: objrepr = safe_repr(self.object) except ValueError: From 391f99d13ac1abc314f9c02629f3d6593cd27879 Mon Sep 17 00:00:00 2001 From: Johannes Dewender Date: Tue, 22 Jan 2013 17:58:47 +0100 Subject: [PATCH 2/4] autodoc: document novalue option The update is listed for version 1.2. This should be changed if the change is released later. --- doc/ext/autodoc.rst | 13 +++++++++++-- 1 file changed, 11 insertions(+), 2 deletions(-) diff --git a/doc/ext/autodoc.rst b/doc/ext/autodoc.rst index 7f9a6c61a..11fd3c8d9 100644 --- a/doc/ext/autodoc.rst +++ b/doc/ext/autodoc.rst @@ -197,8 +197,14 @@ inserting them into the page source under a suitable :rst:dir:`py:module`, automethod autoattribute - These work exactly like :rst:dir:`autoclass` etc., but do not offer the - options used for automatic member documentation. + These work exactly like :rst:dir:`autoclass` etc., + 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:: + + .. autodata:: CD_DRIVE + :novalue: For module data members and class attributes, documentation can either be put into a comment with special formatting (using a ``#:`` to start the comment @@ -234,6 +240,9 @@ inserting them into the page source under a suitable :rst:dir:`py:module`, .. versionchanged:: 1.1 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 + .. note:: If you document decorated functions or methods, keep in mind that autodoc From ffb825d733b428fc469bfd1bb82c2315acd5b081 Mon Sep 17 00:00:00 2001 From: Johannes Dewender Date: Thu, 24 Jan 2013 18:17:53 +0100 Subject: [PATCH 3/4] fix tests for autodoc novalue option In the tests for autodoc the Options are of type struct, while in the code there is a special autodoc.Options class, which is a dict. So "novalue" in self.options doesn't work, but self.options.novalue does work for both. Additionally the logic for autoattribute was wrong and is fixed now. --- sphinx/ext/autodoc.py | 4 ++-- tests/test_autodoc.py | 1 + 2 files changed, 3 insertions(+), 2 deletions(-) diff --git a/sphinx/ext/autodoc.py b/sphinx/ext/autodoc.py index 4181818bc..2bdba7e4f 100644 --- a/sphinx/ext/autodoc.py +++ b/sphinx/ext/autodoc.py @@ -1106,7 +1106,7 @@ class DataDocumenter(ModuleLevelDocumenter): def add_directive_header(self, sig): ModuleLevelDocumenter.add_directive_header(self, sig) - if not "novalue" in self.options: + if not self.options.novalue: try: objrepr = safe_repr(self.object) except ValueError: @@ -1221,7 +1221,7 @@ class AttributeDocumenter(ClassLevelDocumenter): def add_directive_header(self, sig): ClassLevelDocumenter.add_directive_header(self, sig) - if not self._datadescriptor or "novalue" in self.options: + if not self._datadescriptor and not self.options.novalue: try: objrepr = safe_repr(self.object) except ValueError: diff --git a/tests/test_autodoc.py b/tests/test_autodoc.py index be6c4ec9c..bef9c3384 100644 --- a/tests/test_autodoc.py +++ b/tests/test_autodoc.py @@ -38,6 +38,7 @@ def setup_module(): special_members = False, show_inheritance = False, noindex = False, + novalue = False, synopsis = '', platform = '', deprecated = False, From 649ab8030c8cab249cd0be28616a0f87b97571dd Mon Sep 17 00:00:00 2001 From: Johannes Dewender Date: Wed, 27 Feb 2013 16:38:55 +0100 Subject: [PATCH 4/4] 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. --- doc/ext/autodoc.rst | 16 +++++++++++++--- sphinx/ext/autodoc.py | 31 +++++++++++++++++++++++++------ tests/test_autodoc.py | 2 +- 3 files changed, 39 insertions(+), 10 deletions(-) diff --git a/doc/ext/autodoc.rst b/doc/ext/autodoc.rst index 11fd3c8d9..4f16723dc 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 2bdba7e4f..07758e3c9 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, '') + elif self.options.annotation is SUPPRESS: + pass + else: + self.add_line(u' :annotation: %s' % self.options.annotation, + '') 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, '') + elif self.options.annotation is SUPPRESS: + pass + else: + self.add_line(u' :annotation: %s' % self.options.annotation, + '') 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 bef9c3384..95eda5906 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,