Stack Overflow
Stack Overflow

Questions tagged [sphinx-napoleon]

Napoleon is an extension for the Sphinx documentation generator, which adds support for Google and NumPy docstrings.

Napoleon is an extension for the Sphinx documentation generator. It is written by Rob Ruana and is licensed under the 2-clause BSD License.

It allows you to avoid the use of reStructuredText in docstrings, that make them more difficult to read. Instead, it enables support for legible, easy-to-read docstrings by using Google and/or NumPy-style docstrings. To achieve this, Napoleon first processes the docstrings and converts them to reStructuredText. However, reStructuredText will still be available for use while using Napoleon.

Every docstring (on modules, classes, attributes, methods, functions and variables) can be processed with Napoleon.

58 questions
86
votes
3 answers

Custom PyCharm docstring stubs (i.e. for google docstring or numpydoc formats)

Does PyCharm 2.7 (or will PyCharm 3) have support for custom docstring and doctest stubs? If so, how does one go about writing this specific type of custom extension? My current project has standardized on using the Google Python Style Guide…
kalefranz
  • 4,612
  • 2
  • 27
  • 42
57
votes
1 answer

How to express multiple types for a single parameter or a return value in docstrings that are processed by Sphinx?

Sometimes a function in Python may accept an argument of a flexible type. Or it may return a value of a flexible type. Now I can't remember a good example of such a function right now, therefore I am demonstrating what such a function may look like…
Lone Learner
  • 18,088
  • 20
  • 102
  • 200
53
votes
4 answers

Sphinx autosummary "toctree contains reference to nonexisting document" warnings

I am trying to automatically create api docs for a large python codebase using Sphinx. I have tried using build_modules.py and sphinx-apidoc. With either one, I can get rst docs successfully created in my output directory for the packages and…
user1287170
  • 713
  • 1
  • 6
  • 8
47
votes
1 answer

How should I document lists, optionals, and yields using Google-style Sphinx?

How do I indicate types for lists, optional arguments and return types for generators on Google-style docstrings using Sphinx-Napoleon? I've tried List[type] list of type Optional[type] type, optional and Yields: type: respectively; but all…
orome
  • 45,163
  • 57
  • 202
  • 418
40
votes
2 answers

Documenting class attributes with type annotations

I want to autogenerate documentation to my code from docstrings. I have some basic class meant to store some data: class DataHolder: """ Class to hold some data Attributes: batch: Run without GUI debug (bool): Show…
Djent
  • 2,877
  • 10
  • 41
  • 66
35
votes
4 answers

Can Sphinx napoleon document function returning multiple arguments?

I am trying to use the Google code style to document a function that I then use sphinx with the napoleon extension to create documentation for. The function is unusual in that is returns two arguments. I don't think napoleon handles this. If so,…
MrCartoonology
  • 1,997
  • 4
  • 22
  • 38
17
votes
4 answers

Force Sphinx to interpret Markdown in Python docstrings instead of reStructuredText

I'm using Sphinx to document a python project. I would like to use Markdown in my docstrings to format them. Even if I use the recommonmark extension, it only covers the .md files written manually, not the docstrings. I use autodoc, napoleon and…
Florentin Hennecker
  • 1,974
  • 23
  • 37
15
votes
2 answers

Simple way to convert Python docstrings from reStructured Text to Google style?

Does anyone now a simple way do convert all docstrings in an existing project from reStructured Text to the Google format? It looks like Napoleon can do something like that, but it looks very complicated, so I figured I'd ask if someone has done…
gmolau
  • 2,815
  • 1
  • 22
  • 45
14
votes
1 answer

Difference between sphinxcontrib.napoleon and numpy.numpydoc

I am writing documentation for a Python project using Numpy-style docstrings. numpydoc and napoleon are two Sphinx extensions that parse Numpy-style docstrings to generate documentation. The first one is used for the Numpy project itself, the second…
ndou
  • 1,048
  • 10
  • 15
13
votes
1 answer

How to automatically add parameter types in sphinx documentation

I am currently trying to implement automatic documentation creation with Sphinx (using the extensions sphinx-apidoc and napoleon). This works quite well, but it would be even better if the typehints (PEP484 convention) are added automatically to the…
Matthijs
  • 439
  • 3
  • 16
13
votes
1 answer

How should I document class and object attributes using Numpy's style?

I've been reading through Numpy's documentation standards, and it doesn't seem to make a mention of object attributes - only class attributes. So, for instance, how would I document the following? class ClassA(object): """Short description of…
Nick Sweet
  • 2,030
  • 3
  • 31
  • 48
11
votes
2 answers

List of class methods with Napoleon Sphinx extension using NumPyDoc style

I am using NumPyDoc-style docstrings to document a Python package. I would like to switch from the 'numpydoc' Sphinx extension to Napoleon, because I find that it formats the docstring in a more compact and readable way. However, it does not list…
Pietro Marchesi
  • 852
  • 2
  • 8
  • 18
11
votes
4 answers

Should you always document functions, even if redundant (specifically python)?

I try to use function names that are active and descriptive, which I then document with active and descriptive text (!). This generates redundant-looking code. Simplified (but not so unrealistic) example in python, following numpy docstring…
barford
  • 119
  • 1
  • 4
10
votes
3 answers

sphinx warning: autosummary: stub file not found for the methods of the class. check your autosummary_generate settings

I have an open source package with lots of classes over different submodules. All classes have methods fit and transform, and inherit fit_transform from sklearn. All classes have docstrings that follow numpydoc with subheadings Parameters,…
Sole Galli
  • 827
  • 6
  • 21
10
votes
2 answers

How to specify multiple return types in a function docstring in Python?

I am aware of the syntax used to build a docstring for Google style such as: def function_with_types_in_docstring(param1, param2): """Example function with types documented in the docstring. `PEP 484`_ type annotations are supported. If…
Alex Tereshenkov
  • 3,340
  • 8
  • 36
  • 61
1
2 3 4