← Back to branch summary

~andrewsomething/ubuntu/precise/sphinx/1.1.3+dfsg-2ubuntu1

« back to all changes in this revision

Viewing changes to .pc/docstring_parse.diff/doc/ext/autodoc.rst

  • Committer: Bazaar Package Importer
  • Author(s): Jakub Wilk, Jakub Wilk, Nikolaus Rath
  • Date: 2011-06-19 14:44:49 UTC
  • mfrom: (5.3.5 sid)
  • Revision ID: james.westby@ubuntu.com-20110619144449-tqs2d2q0w9ihepbn
Tags: 1.0.7-5
http://bugs.debian.org/630973
http://bugs.debian.org/630409
[ Jakub Wilk ]
* Bump standards version to 3.9.2 (no changes needed).
* Bump minimum required version of jQuery to 1.4.
* Use python (>= 2.6.6-14~) as an alternative build-dependency to
  python-simplejson. The latter package is only needed for python2.5, and
  python-defaults 2.6.6-14 doesn't support it anymore.
* Include jQuery source (closes: #630973).
  + Check at build time if versions of both jQuery copies match.

[ Nikolaus Rath ]
* Backport upstream changesets a8b0ef275438 and de340a6098c7 to allow
  extraction of function signature from docstring for extension modules.
  (closes: #630409). The feature is disabled by default for the moment.

Show diffs side-by-side

added added

removed removed

Lines of Context:
.pc/docstring_parse.diff/doc/ext/autodoc.rst
 
1
.. highlight:: rest
 
2
 
 
3
:mod:`sphinx.ext.autodoc` -- Include documentation from docstrings
 
4
==================================================================
 
5
 
 
6
.. module:: sphinx.ext.autodoc
 
7
   :synopsis: Include documentation from docstrings.
 
8
 
 
9
.. index:: pair: automatic; documentation
 
10
           single: docstring
 
11
 
 
12
This extension can import the modules you are documenting, and pull in
 
13
documentation from docstrings in a semi-automatic way.
 
14
 
 
15
.. note::
 
16
 
 
17
   For Sphinx (actually, the Python interpreter that executes Sphinx) to find
 
18
   your module, it must be importable.  That means that the module or the
 
19
   package must be in one of the directories on :data:`sys.path` -- adapt your
 
20
   :data:`sys.path` in the configuration file accordingly.
 
21
 
 
22
For this to work, the docstrings must of course be written in correct
 
23
reStructuredText.  You can then use all of the usual Sphinx markup in the
 
24
docstrings, and it will end up correctly in the documentation.  Together with
 
25
hand-written documentation, this technique eases the pain of having to maintain
 
26
two locations for documentation, while at the same time avoiding
 
27
auto-generated-looking pure API documentation.
 
28
 
 
29
:mod:`autodoc` provides several directives that are versions of the usual
 
30
:rst:dir:`py:module`, :rst:dir:`py:class` and so forth.  On parsing time, they
 
31
import the corresponding module and extract the docstring of the given objects,
 
32
inserting them into the page source under a suitable :rst:dir:`py:module`,
 
33
:rst:dir:`py:class` etc.  directive.
 
34
 
 
35
.. note::
 
36
 
 
37
   Just as :rst:dir:`py:class` respects the current :rst:dir:`py:module`,
 
38
   :rst:dir:`autoclass` will also do so.  Likewise, :rst:dir:`automethod` will
 
39
   respect the current :rst:dir:`py:class`.
 
40
 
 
41
 
 
42
.. rst:directive:: automodule
 
43
                   autoclass
 
44
                   autoexception
 
45
 
 
46
   Document a module, class or exception.  All three directives will by default
 
47
   only insert the docstring of the object itself::
 
48
 
 
49
      .. autoclass:: Noodle
 
50
 
 
51
   will produce source like this::
 
52
 
 
53
      .. class:: Noodle
 
54
 
 
55
         Noodle's docstring.
 
56
 
 
57
   The "auto" directives can also contain content of their own, it will be
 
58
   inserted into the resulting non-auto directive source after the docstring
 
59
   (but before any automatic member documentation).
 
60
 
 
61
   Therefore, you can also mix automatic and non-automatic member documentation,
 
62
   like so::
 
63
 
 
64
      .. autoclass:: Noodle
 
65
         :members: eat, slurp
 
66
 
 
67
         .. method:: boil(time=10)
 
68
 
 
69
            Boil the noodle *time* minutes.
 
70
 
 
71
   **Options and advanced usage**
 
72
 
 
73
   * If you want to automatically document members, there's a ``members``
 
74
     option::
 
75
 
 
76
        .. automodule:: noodle
 
77
           :members:
 
78
 
 
79
     will document all module members (recursively), and ::
 
80
 
 
81
        .. autoclass:: Noodle
 
82
           :members:
 
83
 
 
84
     will document all non-private member functions and properties (that is,
 
85
     those whose name doesn't start with ``_``).
 
86
 
 
87
     For modules, ``__all__`` will be respected when looking for members; the
 
88
     order of the members will also be the order in ``__all__``.
 
89
 
 
90
     You can also give an explicit list of members; only these will then be
 
91
     documented::
 
92
 
 
93
        .. autoclass:: Noodle
 
94
           :members: eat, slurp
 
95
 
 
96
   * If you want to make the ``members`` option the default, see
 
97
     :confval:`autodoc_default_flags`.
 
98
 
 
99
   * Members without docstrings will be left out, unless you give the
 
100
     ``undoc-members`` flag option::
 
101
 
 
102
        .. automodule:: noodle
 
103
           :members:
 
104
           :undoc-members:
 
105
 
 
106
   * For classes and exceptions, members inherited from base classes will be
 
107
     left out when documenting all members, unless you give the
 
108
     ``inherited-members`` flag option, in addition to ``members``::
 
109
 
 
110
        .. autoclass:: Noodle
 
111
           :members:
 
112
           :inherited-members:
 
113
 
 
114
     This can be combined with ``undoc-members`` to document *all* available
 
115
     members of the class or module.
 
116
 
 
117
     Note: this will lead to markup errors if the inherited members come from a
 
118
     module whose docstrings are not reST formatted.
 
119
 
 
120
     .. versionadded:: 0.3
 
121
 
 
122
   * It's possible to override the signature for explicitly documented callable
 
123
     objects (functions, methods, classes) with the regular syntax that will
 
124
     override the signature gained from introspection::
 
125
 
 
126
        .. autoclass:: Noodle(type)
 
127
 
 
128
           .. automethod:: eat(persona)
 
129
 
 
130
     This is useful if the signature from the method is hidden by a decorator.
 
131
 
 
132
     .. versionadded:: 0.4
 
133
 
 
134
   * The :rst:dir:`automodule`, :rst:dir:`autoclass` and
 
135
     :rst:dir:`autoexception` directives also support a flag option called
 
136
     ``show-inheritance``.  When given, a list of base classes will be inserted
 
137
     just below the class signature (when used with :rst:dir:`automodule`, this
 
138
     will be inserted for every class that is documented in the module).
 
139
 
 
140
     .. versionadded:: 0.4
 
141
 
 
142
   * All autodoc directives support the ``noindex`` flag option that has the
 
143
     same effect as for standard :rst:dir:`py:function` etc. directives: no
 
144
     index entries are generated for the documented object (and all
 
145
     autodocumented members).
 
146
 
 
147
     .. versionadded:: 0.4
 
148
 
 
149
   * :rst:dir:`automodule` also recognizes the ``synopsis``, ``platform`` and
 
150
     ``deprecated`` options that the standard :rst:dir:`py:module` directive
 
151
     supports.
 
152
 
 
153
     .. versionadded:: 0.5
 
154
 
 
155
   * :rst:dir:`automodule` and :rst:dir:`autoclass` also has an ``member-order`` option
 
156
     that can be used to override the global value of
 
157
     :confval:`autodoc_member_order` for one directive.
 
158
 
 
159
     .. versionadded:: 0.6
 
160
 
 
161
   * The directives supporting member documentation also have a
 
162
     ``exclude-members`` option that can be used to exclude single member names
 
163
     from documentation, if all members are to be documented.
 
164
 
 
165
     .. versionadded:: 0.6
 
166
 
 
167
   .. note::
 
168
 
 
169
      In an :rst:dir:`automodule` directive with the ``members`` option set, only
 
170
      module members whose ``__module__`` attribute is equal to the module name
 
171
      as given to ``automodule`` will be documented.  This is to prevent
 
172
      documentation of imported classes or functions.
 
173
 
 
174
 
 
175
.. rst:directive:: autofunction
 
176
               autodata
 
177
               automethod
 
178
               autoattribute
 
179
 
 
180
   These work exactly like :rst:dir:`autoclass` etc., but do not offer the options
 
181
   used for automatic member documentation.
 
182
 
 
183
   For module data members and class attributes, documentation can either be put
 
184
   into a special-formatted comment *before* the attribute definition, or in a
 
185
   docstring *after* the definition.  This means that in the following class
 
186
   definition, both attributes can be autodocumented::
 
187
 
 
188
      class Foo:
 
189
          """Docstring for class Foo."""
 
190
 
 
191
          #: Doc comment for attribute Foo.bar.
 
192
          bar = 1
 
193
 
 
194
          baz = 2
 
195
          """Docstring for attribute Foo.baz."""
 
196
 
 
197
   .. versionchanged:: 0.6
 
198
      :rst:dir:`autodata` and :rst:dir:`autoattribute` can now extract docstrings.
 
199
 
 
200
   .. note::
 
201
 
 
202
      If you document decorated functions or methods, keep in mind that autodoc
 
203
      retrieves its docstrings by importing the module and inspecting the
 
204
      ``__doc__`` attribute of the given function or method.  That means that if
 
205
      a decorator replaces the decorated function with another, it must copy the
 
206
      original ``__doc__`` to the new function.
 
207
 
 
208
      From Python 2.5, :func:`functools.wraps` can be used to create
 
209
      well-behaved decorating functions.
 
210
 
 
211
 
 
212
There are also new config values that you can set:
 
213
 
 
214
.. confval:: autoclass_content
 
215
 
 
216
   This value selects what content will be inserted into the main body of an
 
217
   :rst:dir:`autoclass` directive.  The possible values are:
 
218
 
 
219
   ``"class"``
 
220
      Only the class' docstring is inserted.  This is the default.  You can
 
221
      still document ``__init__`` as a separate method using
 
222
      :rst:dir:`automethod` or the ``members`` option to :rst:dir:`autoclass`.
 
223
   ``"both"``
 
224
      Both the class' and the ``__init__`` method's docstring are concatenated
 
225
      and inserted.
 
226
   ``"init"``
 
227
      Only the ``__init__`` method's docstring is inserted.
 
228
 
 
229
   .. versionadded:: 0.3
 
230
 
 
231
.. confval:: autodoc_member_order
 
232
 
 
233
   This value selects if automatically documented members are sorted
 
234
   alphabetical (value ``'alphabetical'``), by member type (value
 
235
   ``'groupwise'``) or by source order (value ``'bysource'``).  The default is
 
236
   alphabetical.
 
237
 
 
238
   Note that for source order, the module must be a Python module with the
 
239
   source code available.
 
240
 
 
241
   .. versionadded:: 0.6
 
242
   .. versionchanged:: 1.0
 
243
      Support for ``'bysource'``.
 
244
 
 
245
.. confval:: autodoc_default_flags
 
246
 
 
247
   This value is a list of autodoc directive flags that should be automatically
 
248
   applied to all autodoc directives.  The supported flags are ``'members'``,
 
249
   ``'undoc-members'``, ``'inherited-members'`` and ``'show-inheritance'``.
 
250
 
 
251
   If you set one of these flags in this config value, you can use a negated
 
252
   form, :samp:`'no-{flag}'`, in an autodoc directive, to disable it once.
 
253
   For example, if ``autodoc_default_flags`` is set to ``['members',
 
254
   'undoc-members']``, and you write a directive like this::
 
255
 
 
256
      .. automodule:: foo
 
257
         :no-undoc-members:
 
258
 
 
259
   the directive will be interpreted as if only ``:members:`` was given.
 
260
 
 
261
   .. versionadded:: 1.0
 
262
 
 
263
 
 
264
Docstring preprocessing
 
265
-----------------------
 
266
 
 
267
autodoc provides the following additional events:
 
268
 
 
269
.. event:: autodoc-process-docstring (app, what, name, obj, options, lines)
 
270
 
 
271
   .. versionadded:: 0.4
 
272
 
 
273
   Emitted when autodoc has read and processed a docstring.  *lines* is a list
 
274
   of strings -- the lines of the processed docstring -- that the event handler
 
275
   can modify **in place** to change what Sphinx puts into the output.
 
276
 
 
277
   :param app: the Sphinx application object
 
278
   :param what: the type of the object which the docstring belongs to (one of
 
279
      ``"module"``, ``"class"``, ``"exception"``, ``"function"``, ``"method"``,
 
280
      ``"attribute"``)
 
281
   :param name: the fully qualified name of the object
 
282
   :param obj: the object itself
 
283
   :param options: the options given to the directive: an object with attributes
 
284
      ``inherited_members``, ``undoc_members``, ``show_inheritance`` and
 
285
      ``noindex`` that are true if the flag option of same name was given to the
 
286
      auto directive
 
287
   :param lines: the lines of the docstring, see above
 
288
 
 
289
.. event:: autodoc-process-signature (app, what, name, obj, options, signature, return_annotation)
 
290
 
 
291
   .. versionadded:: 0.5
 
292
 
 
293
   Emitted when autodoc has formatted a signature for an object. The event
 
294
   handler can return a new tuple ``(signature, return_annotation)`` to change
 
295
   what Sphinx puts into the output.
 
296
 
 
297
   :param app: the Sphinx application object
 
298
   :param what: the type of the object which the docstring belongs to (one of
 
299
      ``"module"``, ``"class"``, ``"exception"``, ``"function"``, ``"method"``,
 
300
      ``"attribute"``)
 
301
   :param name: the fully qualified name of the object
 
302
   :param obj: the object itself
 
303
   :param options: the options given to the directive: an object with attributes
 
304
      ``inherited_members``, ``undoc_members``, ``show_inheritance`` and
 
305
      ``noindex`` that are true if the flag option of same name was given to the
 
306
      auto directive
 
307
   :param signature: function signature, as a string of the form
 
308
      ``"(parameter_1, parameter_2)"``, or ``None`` if introspection didn't succeed
 
309
      and signature wasn't specified in the directive.
 
310
   :param return_annotation: function return annotation as a string of the form
 
311
      ``" -> annotation"``, or ``None`` if there is no return annotation
 
312
 
 
313
The :mod:`sphinx.ext.autodoc` module provides factory functions for commonly
 
314
needed docstring processing in event :event:`autodoc-process-docstring`:
 
315
 
 
316
.. autofunction:: cut_lines
 
317
.. autofunction:: between
 
318
 
 
319
 
 
320
Skipping members
 
321
----------------
 
322
 
 
323
autodoc allows the user to define a custom method for determining whether a
 
324
member should be included in the documentation by using the following event:
 
325
 
 
326
.. event:: autodoc-skip-member (app, what, name, obj, skip, options)
 
327
 
 
328
   .. versionadded:: 0.5
 
329
 
 
330
   Emitted when autodoc has to decide whether a member should be included in the
 
331
   documentation.  The member is excluded if a handler returns ``True``.  It is
 
332
   included if the handler returns ``False``.
 
333
 
 
334
   :param app: the Sphinx application object
 
335
   :param what: the type of the object which the docstring belongs to (one of
 
336
      ``"module"``, ``"class"``, ``"exception"``, ``"function"``, ``"method"``,
 
337
      ``"attribute"``)
 
338
   :param name: the fully qualified name of the object
 
339
   :param obj: the object itself
 
340
   :param skip: a boolean indicating if autodoc will skip this member if the user
 
341
      handler does not override the decision
 
342
   :param options: the options given to the directive: an object with attributes
 
343
      ``inherited_members``, ``undoc_members``, ``show_inheritance`` and
 
344
      ``noindex`` that are true if the flag option of same name was given to the
 
345
      auto directive