diff options
| -rw-r--r-- | CHANGES | 4 | ||||
| -rw-r--r-- | EXAMPLES | 7 | ||||
| -rw-r--r-- | doc/ext/napoleon.rst | 3 | ||||
| -rw-r--r-- | sphinx/ext/autodoc.py | 19 | ||||
| -rw-r--r-- | sphinx/ext/mathjax.py | 4 | ||||
| -rw-r--r-- | sphinx/ext/napoleon/__init__.py | 3 | ||||
| -rw-r--r-- | sphinx/ext/napoleon/docstring.py | 6 | ||||
| -rw-r--r-- | tests/test_autodoc.py | 47 | ||||
| -rw-r--r-- | tests/test_napoleon_docstring.py | 31 |
9 files changed, 117 insertions, 7 deletions
@@ -148,7 +148,9 @@ Bugs fixed * #1466,PR#241: Fix failure of the cpp domain parser to parse C+11 "variadic templates" declarations. Thanks to Victor Zverovich. * #1459,PR#244: Fix default mathjax js path point to `http://` that cause - mixed-content error on HTTPS server. Thanks to sbrandtb. + mixed-content error on HTTPS server. Thanks to sbrandtb and robo9k. +* PR#157: autodoc remove spurious signatures from @property decorated + attributes. Thanks to David Ham. Documentation ------------- @@ -131,6 +131,7 @@ Documentation using another builtin theme * libLAS: http://liblas.org/ (nature) * MPipe: http://vmlaker.github.io/mpipe/ (sphinx13) * pip: http://pip.openplans.org/ (nature) +* Pyramid web framework: http://docs.pylonsproject.org/projects/pyramid/en/latest/ (pyramid) * Programmieren mit PyGTK und Glade (German): http://www.florian-diesch.de/doc/python-und-glade/online/ (agogo) * Spring Python: http://springpython.webfactional.com/current/sphinx/index.html @@ -159,6 +160,7 @@ Documentation using a custom theme/integrated in a site * GeoServer: http://docs.geoserver.org/ * Glashammer: http://glashammer.org/ * Istihza (Turkish Python documentation project): http://www.istihza.com/py2/icindekiler_python.html +* Lasso: http://lassoguide.com/ * MathJax: http://docs.mathjax.org/en/latest/ * MirrorBrain: http://mirrorbrain.org/docs/ * nose: http://somethingaboutorange.com/mrl/projects/nose/ @@ -172,7 +174,7 @@ Documentation using a custom theme/integrated in a site * PyEphem: http://rhodesmill.org/pyephem/ * German Plone user manual: http://www.hasecke.com/plone-benutzerhandbuch/ * PSI4: http://sirius.chem.vt.edu/psi4manual/latest/index.html -* Pylons: http://pylonshq.com/docs/en/0.9.7/ +* Pylons: http://docs.pylonsproject.org/projects/pylons-webframework/en/latest/ * PyMOTW: http://www.doughellmann.com/PyMOTW/ * pypol: http://pypol.altervista.org/ (celery) * QGIS: http://qgis.org/ @@ -180,6 +182,7 @@ Documentation using a custom theme/integrated in a site * Roundup: http://www.roundup-tracker.org/ * Selenium: http://seleniumhq.org/docs/ * Self: http://selflanguage.org/ +* Substance D: http://docs.pylonsproject.org/projects/substanced/en/latest/ * Tablib: http://tablib.org/ * SQLAlchemy: http://www.sqlalchemy.org/docs/ * tinyTiM: http://tinytim.sourceforge.net/docs/2.0/ @@ -224,6 +227,8 @@ Books produced using Sphinx https://www.varnish-software.com/static/book/ * "Learning Sphinx" (in Japanese): http://www.oreilly.co.jp/books/9784873116488/ +* "LassoGuide": + http://www.lassosoft.com/Lasso-Documentation Thesis using Sphinx diff --git a/doc/ext/napoleon.rst b/doc/ext/napoleon.rst index 7248e4912..26d494dbf 100644 --- a/doc/ext/napoleon.rst +++ b/doc/ext/napoleon.rst @@ -324,7 +324,8 @@ enabled in `conf.py`:: **If False**:: .. attribute:: attr1 - :annotation: int + + *int* Description of `attr1` diff --git a/sphinx/ext/autodoc.py b/sphinx/ext/autodoc.py index cb01cfcee..5938f30f1 100644 --- a/sphinx/ext/autodoc.py +++ b/sphinx/ext/autodoc.py @@ -971,6 +971,23 @@ class DocstringSignatureMixin(object): self.args, self.retann = result return Documenter.format_signature(self) +class DocstringStripSignatureMixin(DocstringSignatureMixin): + """ + Mixin for AttributeDocumenter to provide the + feature of stripping any function signature from the docstring. + """ + def format_signature(self): + if self.args is None and self.env.config.autodoc_docstring_signature: + # only act if a signature is not explicitly given already, and if + # the feature is enabled + result = self._find_signature() + if result is not None: + # Discarding _args is a only difference with + # DocstringSignatureMixin.format_signature. + # Documenter.format_signature use self.args value to format. + _args, self.retann = result + return Documenter.format_signature(self) + class FunctionDocumenter(DocstringSignatureMixin, ModuleLevelDocumenter): """ @@ -1247,7 +1264,7 @@ class MethodDocumenter(DocstringSignatureMixin, ClassLevelDocumenter): pass -class AttributeDocumenter(ClassLevelDocumenter): +class AttributeDocumenter(DocstringStripSignatureMixin,ClassLevelDocumenter): """ Specialized Documenter subclass for attributes. """ diff --git a/sphinx/ext/mathjax.py b/sphinx/ext/mathjax.py index f7914b2fb..472ec55fd 100644 --- a/sphinx/ext/mathjax.py +++ b/sphinx/ext/mathjax.py @@ -60,8 +60,10 @@ def builder_inited(app): def setup(app): mathbase_setup(app, (html_visit_math, None), (html_visit_displaymath, None)) + # more information for mathjax secure url is here: + # http://docs.mathjax.org/en/latest/start.html#secure-access-to-the-cdn app.add_config_value('mathjax_path', - 'https://cdn.mathjax.org/mathjax/latest/MathJax.js?' + 'https://c328740.ssl.cf1.rackcdn.com/mathjax/latest/MathJax.js?' 'config=TeX-AMS-MML_HTMLorMML', False) app.add_config_value('mathjax_inline', [r'\(', r'\)'], 'html') app.add_config_value('mathjax_display', [r'\[', r'\]'], 'html') diff --git a/sphinx/ext/napoleon/__init__.py b/sphinx/ext/napoleon/__init__.py index b67ea79c0..655a07a05 100644 --- a/sphinx/ext/napoleon/__init__.py +++ b/sphinx/ext/napoleon/__init__.py @@ -151,7 +151,8 @@ class Config(object): **If False**:: .. attribute:: attr1 - :annotation: int + + *int* Description of `attr1` diff --git a/sphinx/ext/napoleon/docstring.py b/sphinx/ext/napoleon/docstring.py index 1a8d88c6a..19f5f395a 100644 --- a/sphinx/ext/napoleon/docstring.py +++ b/sphinx/ext/napoleon/docstring.py @@ -428,7 +428,11 @@ class GoogleDocstring(UnicodeMixin): else: lines.append('.. attribute:: ' + _name) if _type: - lines.append(' :annotation: ' + _type) + lines.append('') + if '`' in _type: + lines.append(' %s' % _type) + else: + lines.append(' *%s*' % _type) if _desc: lines.extend([''] + self._indent(_desc, 3)) lines.append('') diff --git a/tests/test_autodoc.py b/tests/test_autodoc.py index 06b86568c..d100b5550 100644 --- a/tests/test_autodoc.py +++ b/tests/test_autodoc.py @@ -416,6 +416,39 @@ def test_docstring_processing(): @with_setup(setup_test) +def test_docstring_property_processing(): + def genarate_docstring(objtype, name, **kw): + del processed_docstrings[:] + del processed_signatures[:] + inst = AutoDirective._registry[objtype](directive, name) + inst.generate(**kw) + results = list(directive.result) + docstrings = inst.get_doc()[0] + del directive.result[:] + return results, docstrings + + directive.env.config.autodoc_docstring_signature = False + results, docstrings = genarate_docstring('attribute', 'test_autodoc.DocstringSig.prop1') + assert '.. py:attribute:: DocstringSig.prop1' in results + assert 'First line of docstring' in docstrings + assert 'DocstringSig.prop1(self)' in docstrings + results, docstrings = genarate_docstring('attribute', 'test_autodoc.DocstringSig.prop2') + assert '.. py:attribute:: DocstringSig.prop2' in results + assert 'First line of docstring' in docstrings + assert 'Second line of docstring' in docstrings + + directive.env.config.autodoc_docstring_signature = True + results, docstrings = genarate_docstring('attribute', 'test_autodoc.DocstringSig.prop1') + assert '.. py:attribute:: DocstringSig.prop1' in results + assert 'First line of docstring' in docstrings + assert 'DocstringSig.prop1(self)' not in docstrings + results, docstrings = genarate_docstring('attribute', 'test_autodoc.DocstringSig.prop2') + assert '.. py:attribute:: DocstringSig.prop2' in results + assert 'First line of docstring' in docstrings + assert 'Second line of docstring' in docstrings + + +@with_setup(setup_test) def test_new_documenter(): class MyDocumenter(ModuleLevelDocumenter): objtype = 'integer' @@ -873,6 +906,20 @@ First line of docstring indented line """ + @property + def prop1(self): + """DocstringSig.prop1(self) + First line of docstring + """ + return 123 + + @property + def prop2(self): + """First line of docstring + Second line of docstring + """ + return 456 + class StrRepr(str): def __repr__(self): return self diff --git a/tests/test_napoleon_docstring.py b/tests/test_napoleon_docstring.py index 34ba4e418..b731072a2 100644 --- a/tests/test_napoleon_docstring.py +++ b/tests/test_napoleon_docstring.py @@ -205,6 +205,37 @@ This class should only be used by runtimes. """ self.assertEqual(expected, actual) + def test_attributes_with_class_reference(self): + docstring = """\ +Attributes: + in_attr(:class:`numpy.ndarray`): super-dooper attribute +""" + + actual = str(GoogleDocstring(docstring)) + expected = """\ +.. attribute:: in_attr + + :class:`numpy.ndarray` + + super-dooper attribute +""" + self.assertEqual(expected, actual) + + docstring = """\ +Attributes: + in_attr(numpy.ndarray): super-dooper attribute +""" + + actual = str(GoogleDocstring(docstring)) + expected = """\ +.. attribute:: in_attr + + *numpy.ndarray* + + super-dooper attribute +""" + self.assertEqual(expected, actual) + class NumpyDocstringTest(BaseDocstringTest): docstrings = [( |