summaryrefslogtreecommitdiffstats
path: root/doc/usage/extensions/napoleon.rst
blob: 4b077defe97f434b54aac15ba06cdf41fb99e42d (plain)
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
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
:mod:`sphinx.ext.napoleon` -- Support for NumPy and Google style docstrings
===========================================================================

.. module:: sphinx.ext.napoleon
   :synopsis: Support for NumPy and Google style docstrings

.. moduleauthor:: Rob Ruana

.. versionadded:: 1.3

Overview
--------

.. highlight:: text

Are you tired of writing docstrings that look like this::

    :param path: The path of the file to wrap
    :type path: str
    :param field_storage: The :class:`FileStorage` instance to wrap
    :type field_storage: FileStorage
    :param temporary: Whether or not to delete the file when the File
       instance is destructed
    :type temporary: bool
    :returns: A buffered writable file descriptor
    :rtype: BufferedFileStorage

`reStructuredText`_ is great, but it creates visually dense, hard to read
:pep:`docstrings <287>`. Compare the jumble above to the same thing rewritten
according to the `Google Python Style Guide`_::

    Args:
        path (str): The path of the file to wrap
        field_storage (FileStorage): The :class:`FileStorage` instance to wrap
        temporary (bool): Whether or not to delete the file when the File
           instance is destructed

    Returns:
        BufferedFileStorage: A buffered writable file descriptor

Much more legible, no?

Napoleon is a :term:`extension` that enables Sphinx to parse both `NumPy`_ and
`Google`_ style docstrings - the style recommended by `Khan Academy`_.

Napoleon is a pre-processor that parses `NumPy`_ and `Google`_ style
docstrings and converts them to reStructuredText before Sphinx attempts to
parse them. This happens in an intermediate step while Sphinx is processing
the documentation, so it doesn't modify any of the docstrings in your actual
source code files.

.. _ReStructuredText: https://docutils.sourceforge.io/rst.html
.. _Google Python Style Guide:
   https://google.github.io/styleguide/pyguide.html
.. _Google:
   https://google.github.io/styleguide/pyguide.html#38-comments-and-docstrings
.. _NumPy:
   https://numpydoc.readthedocs.io/en/latest/format.html#docstring-standard
.. _Khan Academy:
   https://github.com/Khan/style-guides/blob/master/style/python.md#docstrings

Getting Started
~~~~~~~~~~~~~~~

1. After :doc:`setting up Sphinx </usage/quickstart>` to build your docs,
   enable napoleon in the Sphinx ``conf.py`` file::

       # conf.py

       # Add napoleon to the extensions list
       extensions = ['sphinx.ext.napoleon']

2. Use ``sphinx-apidoc`` to build your API documentation::

       $ sphinx-apidoc -f -o docs/source projectdir


Docstrings
~~~~~~~~~~

Napoleon interprets every docstring that :mod:`autodoc <sphinx.ext.autodoc>`
can find, including docstrings on: ``modules``, ``classes``, ``attributes``,
``methods``, ``functions``, and ``variables``. Inside each docstring,
specially formatted `Sections`_ are parsed and converted to
reStructuredText.

All standard reStructuredText formatting still works as expected.


.. _Sections:

Docstring Sections
~~~~~~~~~~~~~~~~~~

All of the following section headers are supported:

* ``Args`` *(alias of Parameters)*
* ``Arguments`` *(alias of Parameters)*
* ``Attention``
* ``Attributes``
* ``Caution``
* ``Danger``
* ``Error``
* ``Example``
* ``Examples``
* ``Hint``
* ``Important``
* ``Keyword Args`` *(alias of Keyword Arguments)*
* ``Keyword Arguments``
* ``Methods``
* ``Note``
* ``Notes``
* ``Other Parameters``
* ``Parameters``
* ``Return`` *(alias of Returns)*
* ``Returns``
* ``Raise`` *(alias of Raises)*
* ``Raises``
* ``References``
* ``See Also``
* ``Tip``
* ``Todo``
* ``Warning``
* ``Warnings`` *(alias of Warning)*
* ``Warn`` *(alias of Warns)*
* ``Warns``
* ``Yield`` *(alias of Yields)*
* ``Yields``

Google vs NumPy
~~~~~~~~~~~~~~~

Napoleon supports two styles of docstrings: `Google`_ and `NumPy`_. The
main difference between the two styles is that Google uses indentation to
separate sections, whereas NumPy uses underlines.

Google style:

.. code-block:: python

    def func(arg1, arg2):
        """Summary line.

        Extended description of function.

        Args:
            arg1 (int): Description of arg1
            arg2 (str): Description of arg2

        Returns:
            bool: Description of return value

        """
        return True

NumPy style:

.. code-block:: python

    def func(arg1, arg2):
        """Summary line.

        Extended description of function.

        Parameters
        ----------
        arg1 : int
            Description of arg1
        arg2 : str
            Description of arg2

        Returns
        -------
        bool
            Description of return value

        """
        return True

NumPy style tends to require more vertical space, whereas Google style
tends to use more horizontal space. Google style tends to be easier to
read for short and simple docstrings, whereas NumPy style tends be easier
to read for long and in-depth docstrings.

The choice between styles is largely aesthetic, but the two styles should
not be mixed. Choose one style for your project and be consistent with it.

.. seealso::

   For complete examples:

   * :ref:`example_google`
   * :ref:`example_numpy`


Type Annotations
~~~~~~~~~~~~~~~~

:pep:`484` introduced a standard way to express types in Python code.
This is an alternative to expressing types directly in docstrings.
One benefit of expressing types according to :pep:`484` is that
type checkers and IDEs can take advantage of them for static code
analysis. :pep:`484` was then extended by :pep:`526` which introduced
a similar way to annotate variables (and attributes).

Google style with Python 3 type annotations::

    def func(arg1: int, arg2: str) -> bool:
        """Summary line.

        Extended description of function.

        Args:
            arg1: Description of arg1
            arg2: Description of arg2

        Returns:
            Description of return value

        """
        return True

    class Class:
        """Summary line.

        Extended description of class

        Attributes:
            attr1: Description of attr1
            attr2: Description of attr2
        """

        attr1: int
        attr2: str

Google style with types in docstrings::

    def func(arg1, arg2):
        """Summary line.

        Extended description of function.

        Args:
            arg1 (int): Description of arg1
            arg2 (str): Description of arg2

        Returns:
            bool: Description of return value

        """
        return True

    class Class:
        """Summary line.

        Extended description of class

        Attributes:
            attr1 (int): Description of attr1
            attr2 (str): Description of attr2
        """

.. Note::
   `Python 2/3 compatible annotations`_ aren't currently
   supported by Sphinx and won't show up in the docs.

.. _Python 2/3 compatible annotations: https://peps.python.org/pep-0484/#suggested-syntax-for-python-2-7-and-straddling-code


Configuration
-------------

Listed below are all the settings used by napoleon and their default
values. These settings can be changed in the Sphinx ``conf.py`` file. Make
sure that "sphinx.ext.napoleon" is enabled in ``conf.py``::

    # conf.py

    # Add any Sphinx extension module names here, as strings
    extensions = ['sphinx.ext.napoleon']

    # Napoleon settings
    napoleon_google_docstring = True
    napoleon_numpy_docstring = True
    napoleon_include_init_with_doc = False
    napoleon_include_private_with_doc = False
    napoleon_include_special_with_doc = True
    napoleon_use_admonition_for_examples = False
    napoleon_use_admonition_for_notes = False
    napoleon_use_admonition_for_references = False
    napoleon_use_ivar = False
    napoleon_use_param = True
    napoleon_use_rtype = True
    napoleon_preprocess_types = False
    napoleon_type_aliases = None
    napoleon_attr_annotations = True

.. _Google style:
   https://google.github.io/styleguide/pyguide.html#38-comments-and-docstrings
.. _NumPy style:
   https://numpydoc.readthedocs.io/en/latest/format.html#docstring-standard

.. confval:: napoleon_google_docstring

   True to parse `Google style`_ docstrings. False to disable support
   for Google style docstrings. *Defaults to True.*

.. confval:: napoleon_numpy_docstring

   True to parse `NumPy style`_ docstrings. False to disable support
   for NumPy style docstrings. *Defaults to True.*

.. confval:: napoleon_include_init_with_doc

   True to list ``__init___`` docstrings separately from the class
   docstring. False to fall back to Sphinx's default behavior, which
   considers the ``__init___`` docstring as part of the class
   documentation. *Defaults to False.*

   **If True**::

       def __init__(self):
           """
           This will be included in the docs because it has a docstring
           """

       def __init__(self):
           # This will NOT be included in the docs

.. confval:: napoleon_include_private_with_doc

   True to include private members (like ``_membername``) with docstrings
   in the documentation. False to fall back to Sphinx's default behavior.
   *Defaults to False.*

   **If True**::

       def _included(self):
           """
           This will be included in the docs because it has a docstring
           """
           pass

       def _skipped(self):
           # This will NOT be included in the docs
           pass

.. confval:: napoleon_include_special_with_doc

   True to include special members (like ``__membername__``) with
   docstrings in the documentation. False to fall back to Sphinx's
   default behavior. *Defaults to True.*

   **If True**::

       def __str__(self):
           """
           This will be included in the docs because it has a docstring
           """
           return unicode(self).encode('utf-8')

       def __unicode__(self):
           # This will NOT be included in the docs
           return unicode(self.__class__.__name__)

.. confval:: napoleon_use_admonition_for_examples

   True to use the ``.. admonition::`` directive for the **Example** and
   **Examples** sections. False to use the ``.. rubric::`` directive
   instead. One may look better than the other depending on what HTML
   theme is used. *Defaults to False.*

   This `NumPy style`_ snippet will be converted as follows::

       Example
       -------
       This is just a quick example

   **If True**::

       .. admonition:: Example

          This is just a quick example

   **If False**::

       .. rubric:: Example

       This is just a quick example

.. confval:: napoleon_use_admonition_for_notes

   True to use the ``.. admonition::`` directive for **Notes** sections.
   False to use the ``.. rubric::`` directive instead. *Defaults to False.*

   .. note:: The singular **Note** section will always be converted to a
      ``.. note::`` directive.

   .. seealso::

      :confval:`napoleon_use_admonition_for_examples`

.. confval:: napoleon_use_admonition_for_references

   True to use the ``.. admonition::`` directive for **References**
   sections. False to use the ``.. rubric::`` directive instead.
   *Defaults to False.*

   .. seealso::

      :confval:`napoleon_use_admonition_for_examples`

.. confval:: napoleon_use_ivar

   True to use the ``:ivar:`` role for instance variables. False to use
   the ``.. attribute::`` directive instead. *Defaults to False.*

   This `NumPy style`_ snippet will be converted as follows::

       Attributes
       ----------
       attr1 : int
           Description of `attr1`

   **If True**::

       :ivar attr1: Description of `attr1`
       :vartype attr1: int

   **If False**::

       .. attribute:: attr1

          Description of `attr1`

          :type: int

.. confval:: napoleon_use_param

   True to use a ``:param:`` role for each function parameter. False to
   use a single ``:parameters:`` role for all the parameters.
   *Defaults to True.*

   This `NumPy style`_ snippet will be converted as follows::

       Parameters
       ----------
       arg1 : str
           Description of `arg1`
       arg2 : int, optional
           Description of `arg2`, defaults to 0

   **If True**::

       :param arg1: Description of `arg1`
       :type arg1: str
       :param arg2: Description of `arg2`, defaults to 0
       :type arg2: :class:`int`, *optional*

   **If False**::

       :parameters: * **arg1** (*str*) --
                      Description of `arg1`
                    * **arg2** (*int, optional*) --
                      Description of `arg2`, defaults to 0

.. confval:: napoleon_use_keyword

   True to use a ``:keyword:`` role for each function keyword argument.
   False to use a single ``:keyword arguments:`` role for all the
   keywords.
   *Defaults to True.*

   This behaves similarly to :confval:`napoleon_use_param`. Note unlike docutils,
   ``:keyword:`` and ``:param:`` will not be treated the same way - there will
   be a separate "Keyword Arguments" section, rendered in the same fashion as
   "Parameters" section (type links created if possible)

   .. seealso::

      :confval:`napoleon_use_param`

.. confval:: napoleon_use_rtype

   True to use the ``:rtype:`` role for the return type. False to output
   the return type inline with the description. *Defaults to True.*

   This `NumPy style`_ snippet will be converted as follows::

       Returns
       -------
       bool
           True if successful, False otherwise

   **If True**::

       :returns: True if successful, False otherwise
       :rtype: bool

   **If False**::

       :returns: *bool* -- True if successful, False otherwise

.. confval:: napoleon_preprocess_types

   True to convert the type definitions in the docstrings as references.
   Defaults to *False*.

   .. versionadded:: 3.2.1
   .. versionchanged:: 3.5

      Do preprocess the Google style docstrings also.

.. confval:: napoleon_type_aliases

   A mapping to translate type names to other names or references. Works
   only when ``napoleon_use_param = True``. *Defaults to None.*

   With::

       napoleon_type_aliases = {
           "CustomType": "mypackage.CustomType",
           "dict-like": ":term:`dict-like <mapping>`",
       }

   This `NumPy style`_ snippet::

       Parameters
       ----------
       arg1 : CustomType
           Description of `arg1`
       arg2 : dict-like
           Description of `arg2`

   becomes::

       :param arg1: Description of `arg1`
       :type arg1: mypackage.CustomType
       :param arg2: Description of `arg2`
       :type arg2: :term:`dict-like <mapping>`

   .. versionadded:: 3.2

.. confval:: napoleon_attr_annotations

   True to allow using :pep:`526` attributes annotations in classes.
   If an attribute is documented in the docstring without a type and
   has an annotation in the class body, that type is used.

   .. versionadded:: 3.4

.. confval:: napoleon_custom_sections

   Add a list of custom sections to include, expanding the list of parsed sections.
   *Defaults to None.*

   The entries can either be strings or tuples, depending on the intention:

   * To create a custom "generic" section, just pass a string.
   * To create an alias for an existing section, pass a tuple containing the
     alias name and the original, in that order.
   * To create a custom section that displays like the parameters or returns
     section, pass a tuple containing the custom section name and a string
     value, "params_style" or "returns_style".

   If an entry is just a string, it is interpreted as a header for a generic
   section. If the entry is a tuple/list/indexed container, the first entry
   is the name of the section, the second is the section key to emulate. If the
   second entry value is "params_style" or "returns_style", the custom section
   will be displayed like the parameters section or returns section.

   .. versionadded:: 1.8
   .. versionchanged:: 3.5
      Support ``params_style`` and ``returns_style``