← Back to branch summary

~ubuntu-branches/ubuntu/utopic/python-networkx/utopic

« back to all changes in this revision

Viewing changes to doc/sphinxext/numpydoc.py

  • Committer: Bazaar Package Importer
  • Author(s): Sandro Tosi
  • Date: 2011-03-19 12:19:16 UTC
  • mfrom: (1.2.5 upstream)
  • Revision ID: james.westby@ubuntu.com-20110319121916-xrhlpiwc9sa5e028
Tags: 1.4-1
http://bugs.debian.org/617677
http://bugs.debian.org/608780
* New upstream release; thanks to Yaroslav Halchenko for the report;
  Closes: #617677
* debian/rules
  - don't compress objects.inv; thanks to Michael Fladischer for the report;
    Closes: #608780
* debian/watch
  - updated to point to PyPi
* debian/control
  - bump python-sphinx versioned b-d-i to 1.0.1 minimum
  - added python-pygraphviz to b-d-i, needed for doc building
* debian/copyright
  - bump upstream and packaging copyright years
* debian/patches/{40_add_networkxcss, 50_boundary-test-fix.patch
                  60_remove_svn_refs.diff 70_set_matplotlib_ps_backend.patch}
  - removed since merged upstream
* debian/patches/{10_doc_relocation, 20_example_dirs_remove,
                  30_use_local_objects.inv}
  - refreshed/adapted to new upstream code

Show diffs side-by-side

added added

removed removed

Lines of Context:
doc/sphinxext/numpydoc.py
16
16
 
17
17
"""
18
18
 
 
19
import sphinx
 
20
 
 
21
if sphinx.__version__ < '1.0.1':
 
22
    raise RuntimeError("Sphinx 1.0.1 or newer is required")
 
23
 
19
24
import os, re, pydoc
20
25
from docscrape_sphinx import get_doc_object, SphinxDocString
 
26
from sphinx.util.compat import Directive
21
27
import inspect
22
28
 
23
29
def mangle_docstrings(app, what, name, obj, options, lines,
24
30
                      reference_offset=[0]):
25
31
 
 
32
    cfg = dict(use_plots=app.config.numpydoc_use_plots,
 
33
               show_class_members=app.config.numpydoc_show_class_members)
 
34
 
26
35
    if what == 'module':
27
36
        # Strip top title
28
37
        title_re = re.compile(ur'^\s*[#*=]{4,}\n[a-z0-9 -]+\n[#*=]{4,}\s*',
29
38
                              re.I|re.S)
30
39
        lines[:] = title_re.sub(u'', u"\n".join(lines)).split(u"\n")
31
40
    else:
32
 
        doc = get_doc_object(obj, what, u"\n".join(lines))
33
 
        doc.use_plots = app.config.numpydoc_use_plots
 
41
        doc = get_doc_object(obj, what, u"\n".join(lines), config=cfg)
34
42
        lines[:] = unicode(doc).split(u"\n")
35
43
 
36
44
    if app.config.numpydoc_edit_link and hasattr(obj, '__name__') and \
70
78
def mangle_signature(app, what, name, obj, options, sig, retann):
71
79
    # Do not try to inspect classes that don't define `__init__`
72
80
    if (inspect.isclass(obj) and
73
 
        'initializes x; see ' in pydoc.getdoc(obj.__init__)):
 
81
        (not hasattr(obj, '__init__') or
 
82
        'initializes x; see ' in pydoc.getdoc(obj.__init__))):
74
83
        return '', ''
75
84
 
76
85
    if not (callable(obj) or hasattr(obj, '__argspec_is_invalid_')): return
81
90
        sig = re.sub(u"^[^(]*", u"", doc['Signature'])
82
91
        return sig, u''
83
92
 
84
 
def initialize(app):
85
 
    try:
86
 
        app.connect('autodoc-process-signature', mangle_signature)
87
 
    except:
88
 
        monkeypatch_sphinx_ext_autodoc()
89
 
 
90
93
def setup(app, get_doc_object_=get_doc_object):
91
94
    global get_doc_object
92
95
    get_doc_object = get_doc_object_
93
 
    
 
96
 
94
97
    app.connect('autodoc-process-docstring', mangle_docstrings)
95
 
    app.connect('builder-inited', initialize)
96
 
    app.add_config_value('numpydoc_edit_link', None, True)
 
98
    app.connect('autodoc-process-signature', mangle_signature)
 
99
    app.add_config_value('numpydoc_edit_link', None, False)
97
100
    app.add_config_value('numpydoc_use_plots', None, False)
98
 
 
99
 
#------------------------------------------------------------------------------
100
 
# Monkeypatch sphinx.ext.autodoc to accept argspecless autodocs (Sphinx < 0.5)
101
 
#------------------------------------------------------------------------------
102
 
 
103
 
def monkeypatch_sphinx_ext_autodoc():
104
 
    global _original_format_signature
105
 
    import sphinx.ext.autodoc
106
 
 
107
 
    if sphinx.ext.autodoc.format_signature is our_format_signature:
108
 
        return
109
 
 
110
 
    print "[numpydoc] Monkeypatching sphinx.ext.autodoc ..."
111
 
    _original_format_signature = sphinx.ext.autodoc.format_signature
112
 
    sphinx.ext.autodoc.format_signature = our_format_signature
113
 
 
114
 
def our_format_signature(what, obj):
115
 
    r = mangle_signature(None, what, None, obj, None, None, None)
116
 
    if r is not None:
117
 
        return r[0]
118
 
    else:
119
 
        return _original_format_signature(what, obj)
 
101
    app.add_config_value('numpydoc_show_class_members', True, True)
 
102
 
 
103
    # Extra mangling domains
 
104
    app.add_domain(NumpyPythonDomain)
 
105
    app.add_domain(NumpyCDomain)
 
106
 
 
107
#------------------------------------------------------------------------------
 
108
# Docstring-mangling domains
 
109
#------------------------------------------------------------------------------
 
110
 
 
111
from docutils.statemachine import ViewList
 
112
from sphinx.domains.c import CDomain
 
113
from sphinx.domains.python import PythonDomain
 
114
 
 
115
class ManglingDomainBase(object):
 
116
    directive_mangling_map = {}
 
117
 
 
118
    def __init__(self, *a, **kw):
 
119
        super(ManglingDomainBase, self).__init__(*a, **kw)
 
120
        self.wrap_mangling_directives()
 
121
 
 
122
    def wrap_mangling_directives(self):
 
123
        for name, objtype in self.directive_mangling_map.items():
 
124
            self.directives[name] = wrap_mangling_directive(
 
125
                self.directives[name], objtype)
 
126
 
 
127
class NumpyPythonDomain(ManglingDomainBase, PythonDomain):
 
128
    name = 'np'
 
129
    directive_mangling_map = {
 
130
        'function': 'function',
 
131
        'class': 'class',
 
132
        'exception': 'class',
 
133
        'method': 'function',
 
134
        'classmethod': 'function',
 
135
        'staticmethod': 'function',
 
136
        'attribute': 'attribute',
 
137
    }
 
138
 
 
139
class NumpyCDomain(ManglingDomainBase, CDomain):
 
140
    name = 'np-c'
 
141
    directive_mangling_map = {
 
142
        'function': 'function',
 
143
        'member': 'attribute',
 
144
        'macro': 'function',
 
145
        'type': 'class',
 
146
        'var': 'object',
 
147
    }
 
148
 
 
149
def wrap_mangling_directive(base_directive, objtype):
 
150
    class directive(base_directive):
 
151
        def run(self):
 
152
            env = self.state.document.settings.env
 
153
 
 
154
            name = None
 
155
            if self.arguments:
 
156
                m = re.match(r'^(.*\s+)?(.*?)(\(.*)?', self.arguments[0])
 
157
                name = m.group(2).strip()
 
158
 
 
159
            if not name:
 
160
                name = self.arguments[0]
 
161
 
 
162
            lines = list(self.content)
 
163
            mangle_docstrings(env.app, objtype, name, None, None, lines)
 
164
            self.content = ViewList(lines, self.content.parent)
 
165
 
 
166
            return base_directive.run(self)
 
167
 
 
168
    return directive
 
169