From 4dd3346b289b162e7565e99d388f81ac69628eec Mon Sep 17 00:00:00 2001 From: Georg Brandl Date: Thu, 17 Sep 2009 14:19:18 +0200 Subject: [PATCH 1/5] Add nose. --- EXAMPLES | 1 + 1 file changed, 1 insertion(+) diff --git a/EXAMPLES b/EXAMPLES index ba65cd1b9..07f1cd250 100644 --- a/EXAMPLES +++ b/EXAMPLES @@ -34,6 +34,7 @@ included, please mail to `the Google group * mpmath: http://mpmath.googlecode.com/svn/trunk/doc/build/index.html * MyHDL: http://www.myhdl.org/doc/0.6/ * NetworkX: http://networkx.lanl.gov/ +* nose: http://somethingaboutorange.com/mrl/projects/nose/ * NumPy: http://docs.scipy.org/doc/numpy/reference/ * ObjectListView: http://objectlistview.sourceforge.net/python * OpenEXR: http://excamera.com/articles/26/doc/index.html From 521049d9a8af6ff0466cf9ad543f186b452f77ab Mon Sep 17 00:00:00 2001 From: Georg Brandl Date: Thu, 17 Sep 2009 14:20:46 +0200 Subject: [PATCH 2/5] autodoc: give attributes a higher priority so that descriptors are not documented as methods. --- sphinx/ext/autodoc.py | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/sphinx/ext/autodoc.py b/sphinx/ext/autodoc.py index a5e90b6f4..012244f1e 100644 --- a/sphinx/ext/autodoc.py +++ b/sphinx/ext/autodoc.py @@ -965,10 +965,10 @@ class MethodDocumenter(ClassLevelDocumenter): """ objtype = 'method' member_order = 50 + priority = 0 @classmethod def can_document_member(cls, member, membername, isattr, parent): - # other attributes are recognized via the module analyzer return inspect.isroutine(member) and \ not isinstance(parent, ModuleDocumenter) @@ -1011,6 +1011,10 @@ class AttributeDocumenter(ClassLevelDocumenter): objtype = 'attribute' member_order = 60 + # must be higher than the MethodDocumenter, else it will recognize + # some non-data descriptors as methods + priority = 10 + @classmethod def can_document_member(cls, member, membername, isattr, parent): return (isdescriptor(member) and not From a51e3a4129d0f24a93d89d2bc053fd0192450257 Mon Sep 17 00:00:00 2001 From: Georg Brandl Date: Thu, 8 Oct 2009 09:14:01 +0200 Subject: [PATCH 3/5] Add missing extension. --- doc/conf.py | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/doc/conf.py b/doc/conf.py index e1a48aa20..be79c8f9b 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -6,7 +6,8 @@ import sys, os, re # Add any Sphinx extension module names here, as strings. They can be extensions # coming with Sphinx (named 'sphinx.addons.*') or your custom ones. -extensions = ['sphinx.ext.autodoc', 'sphinx.ext.doctest', 'sphinx.ext.todo'] +extensions = ['sphinx.ext.autodoc', 'sphinx.ext.doctest', 'sphinx.ext.todo', + 'sphinx.ext.autosummary'] # Add any paths that contain templates here, relative to this directory. templates_path = ['_templates'] From 9088649e0f9cccf4d27515874d4553d2699017f2 Mon Sep 17 00:00:00 2001 From: Georg Brandl Date: Sun, 25 Oct 2009 11:09:09 +0100 Subject: [PATCH 4/5] Add "important" to print rule. --- sphinx/themes/basic/static/basic.css | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/sphinx/themes/basic/static/basic.css b/sphinx/themes/basic/static/basic.css index 128114b76..64964c983 100644 --- a/sphinx/themes/basic/static/basic.css +++ b/sphinx/themes/basic/static/basic.css @@ -392,7 +392,7 @@ span.eqno { div.document, div.documentwrapper, div.bodywrapper { - margin: 0; + margin: 0 !important; width: 100%; } From f04ca65690f1d1f63965f24b3b9bd4250f13cc33 Mon Sep 17 00:00:00 2001 From: Georg Brandl Date: Sun, 25 Oct 2009 11:26:10 +0100 Subject: [PATCH 5/5] Fix "fixed" descriptor handling, and add tests. --- CHANGES | 2 ++ sphinx/ext/autodoc.py | 9 ++++++--- tests/test_autodoc.py | 18 ++++++++++++++++++ 3 files changed, 26 insertions(+), 3 deletions(-) diff --git a/CHANGES b/CHANGES index cf7afdb33..c00bbe008 100644 --- a/CHANGES +++ b/CHANGES @@ -1,6 +1,8 @@ Release 0.6.4 (in development) ============================== +* Fix the handling of non-data descriptors in autodoc. + Release 0.6.3 (Sep 03, 2009) ============================ diff --git a/sphinx/ext/autodoc.py b/sphinx/ext/autodoc.py index 012244f1e..f5b988789 100644 --- a/sphinx/ext/autodoc.py +++ b/sphinx/ext/autodoc.py @@ -1015,11 +1015,14 @@ class AttributeDocumenter(ClassLevelDocumenter): # some non-data descriptors as methods priority = 10 + method_types = (FunctionType, BuiltinFunctionType, MethodType) + @classmethod def can_document_member(cls, member, membername, isattr, parent): - return (isdescriptor(member) and not - isinstance(member, (FunctionType, BuiltinFunctionType))) \ - or (not isinstance(parent, ModuleDocumenter) and isattr) + isdatadesc = isdescriptor(member) and not \ + isinstance(member, cls.method_types) + return isdatadesc or \ + (isattr and not isinstance(parent, ModuleDocumenter)) def document_members(self, all_members=False): pass diff --git a/tests/test_autodoc.py b/tests/test_autodoc.py index 8e0114386..687fbd0d7 100644 --- a/tests/test_autodoc.py +++ b/tests/test_autodoc.py @@ -379,6 +379,7 @@ def test_generate(): options.exclude_members = set(['excludemeth']) assert_processes(should, 'class', 'Class') should.extend([('attribute', 'test_autodoc.Class.prop'), + ('attribute', 'test_autodoc.Class.descr'), ('attribute', 'test_autodoc.Class.attr'), ('attribute', 'test_autodoc.Class.docattr'), ('attribute', 'test_autodoc.Class.udocattr')]) @@ -427,6 +428,10 @@ def test_generate(): ('method', 'test_autodoc.Outer.Inner.meth')], 'class', 'Outer', all_members=True) + # test descriptor docstrings + assert_result_contains(' Descriptor instance docstring.', + 'attribute', 'test_autodoc.Class.descr') + # test generation for C modules (which have no source file) directive.env.currmodule = 'time' assert_processes([('function', 'time.asctime')], 'function', 'asctime') @@ -445,6 +450,17 @@ class CustomEx(Exception): def f(self): """Exception method.""" +class CustomDataDescriptor(object): + """Descriptor class docstring.""" + + def __init__(self, doc): + self.__doc__ = doc + + def __get__(self, obj, type=None): + if obj is None: + return self + return 42 + class Base(object): def inheritedmeth(self): """Inherited function.""" @@ -452,6 +468,8 @@ class Base(object): class Class(Base): """Class to document.""" + descr = CustomDataDescriptor("Descriptor instance docstring.") + def meth(self): """Function."""