1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
|
Google and Numpy
================
.. toctree::
:maxdepth: 1
google_demo/index
numpy_demo/index
Pydoctor now supports numpydoc and google style docstrings!
Docstrings will be first converted to reStructuredText and then parsed with ``docutils``.
Any supported `reST markup <restructuredtext.html>`_ can be use to supplement google-style or numpy-style markup.
The main difference between the two styles is that Google uses indentation to separate sections,
whereas NumPy uses underlines. This means that 2 blank lines are needed to end a NumPy section
that is followed by a regular paragraph (i.e. not another section header)
.. note:: We have forked and enhanced the `napoleon Sphinx extension
<https://www.sphinx-doc.org/en/master/usage/extensions/napoleon.html>`_.
For more information, refer to :py:mod:`pydoctor.napoleon` documentation.
For complete markup details, refer to the `Google style <https://google.github.io/styleguide/pyguide.html#38-comments-and-docstrings>`_
or `NumpyDoc style <https://numpydoc.readthedocs.io/en/latest/format.html>`_ reference documentation.
Sections
--------
List of supported sections:
- ``Args``, ``Arguments``, ``Parameters``
- ``Keyword Args``, ``Keyword Arguments``
- ``Return(s)``, ``Yield(s)``
(if you use type annotations a ``Returns`` section will always be present)
- ``Raise(s)``, ``Warn(s)``
- ``See Also``, ``See``
- ``Example(s)``
- ``Note(s)``, ``Warning(s)`` and other admonitions
- ``Attributes`` (Items will be translated into ``ivar`` fields.)
Sections supported on a "best effort" basis:
- ``Methods``: Items will be included into a generic "Methods" section.
- ``References``: Rendered as a generic section.
- ``Other Parameters``, ``Receive(s)``: Parameters described in those sections will be merged with regular parameters.
.. ReST syntax violations might be reported with a slightly incorrect
line number because of this pre-processing. (uncommented this when pydoctor/issues/237 is solved)
|
