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
9
votes
2 answers

Google style docstring Example section is not rendering as a code snippet

I recently started adding documentation to my project and I'm trying to follow the Google style guide. I am using Sphinx to generate the documents and the Sphinx extension napoleon to bridge the gap between the Google styleguide and reST. I have no…
Crystal
  • 5,960
  • 4
  • 21
  • 27
8
votes
1 answer

Is it possible to have a list for a parameter in sphinx.ext.napoleon?

I'm using sphinx autodoc extension together with sphinx.ext.napoleon. I'm following numpydoc style guide since I think it is more readable than google's one. However, I've noticed the following issue which I wasn't able to fix. I have the following…
math
  • 1,868
  • 4
  • 26
  • 60
8
votes
1 answer

How does 'autodoc_default_flags' work in python Sphinx configuration?

I am trying to generate documentation for my python classes using Sphinx 1.4 and sphinx-apidoc and the sphinx.ext.autodoc extension. I have a lot of modules and I want each to only show class names, but not the full list of methods in the class…
sgt_pats
  • 161
  • 3
  • 8
7
votes
2 answers

Sphinx Napoleon Extension: document multiple return arguments with Google Style docstrings

This question is related to this other one. The proposed and accepted solution is: Returns: (tuple): tuple containing: arg1: First Argument arg2: Second Argument This solution…
rdbisme
  • 850
  • 1
  • 13
  • 39
6
votes
1 answer

Sphinx: What is the cause for 'WARNING: duplicate object description'?

I am getting multiple warnings like: WARNING: duplicate object description of pyfar.signal.TimeData.times, other instance in pyfar.classes_audio, use :noindex: for one of them but can not figure out why? Someone suggested that I probably include the…
fabian
  • 103
  • 1
  • 7
5
votes
1 answer

Sphinx remove dataclass fields from autodoc

As this post describes, autodoc will eagerly add the class variables to the documentation even if napoleon adds the fields as documentation in: from dataclasses import dataclass @dataclass class Foo(): """Some class Attributes: a:…
OneRaynyDay
  • 3,658
  • 2
  • 23
  • 56
5
votes
2 answers

Where can I find more information about new syntax supported in Google style docstrings with the napoleon extension of sphinx-doc?

The sphinx-doc napoleon Google style docstrings example here for version 1.3.4 shows that optional arguments for a function/method should be documented as follows: param2 (str, optional): The second parameter. Defaults to None. Second line of…
Lone Learner
  • 18,088
  • 20
  • 102
  • 200
3
votes
1 answer

Using array-like as a type in napoleon without warning

I have a project with some functions documented in the napoleon numpy style. In the spirit of numpyness, I have a bunch of function arguments that are of the class array-like. Here is an example: def foo(x, y): """ Foo the arguments together…
Mad Physicist
  • 107,652
  • 25
  • 181
  • 264
3
votes
2 answers

Documenting class-level variables in Python

I am trying to document a Python class that has some class-level member variables, but I could not get it appropriately documented using reST/Sphinx. The code is this: class OSM: """Some blah and examples""" url =…
PCamargo
  • 584
  • 6
  • 26
3
votes
1 answer

How napoleon and autodoc interact documenting members

I noticed a change in behavior in how Sphinx renders class descriptions. Given this code # my example happens to be a dataclass, but the behavior for # regular classes is the same @dataclass class TestClass: """This is a test class for…
Arne
  • 17,706
  • 5
  • 83
  • 99
3
votes
1 answer

Should I document parameters for similar function signatures?

I have some helper functions that, except for the first argument, take the same arguments as the core function. The parameters are thoroughly documented in the core function. Should I copy-paste this documentation to the helper function too, or…
Zoltán Csáti
  • 679
  • 5
  • 17
3
votes
0 answers

Sphinx and Numpydoc throws parse error when inheriting from third party package

I'm trying to use Sphinx and numpydoc to document my code, yet very unsuccessfully so far. When I m trying to make html I get this very confusing error: Exception occurred: File…
Micromegas
  • 1,499
  • 2
  • 20
  • 49
2
votes
1 answer

How do you define your own latex preamble for sphinx autodoc?

I'd like to use the latex algpseudocode package to add algorithms to my docstrings. I'd also like to be able to define user macros to speed up my maths equation typing in the docstrings. I'm using napoleon autodoc style with sphinx to generate…
dan_sk8r
  • 41
  • 2
2
votes
0 answers

Do you have to type out numpy.ndarray in full for a type hint in a Google-style docstring, or can you just type np.ndarray?

I've been reading through this guide to writing Google-style and Numpy-style docstrings with type hints for numpy ndarrays. In the Numpy-style docstring example, type hints are abbreviated as "np.ndarray". However, in the corresponding Google-style…
dan_sk8r
  • 41
  • 2
2
votes
2 answers

Skipping type hints in documentation

Let's consider the following function: def f(x: int, y: int) -> int: """Get sum of two integers. Parameters ---------- x : int first integer y : int second integer Returns ------- int sum of…
yarnabrina
  • 1,561
  • 1
  • 10
  • 30
1
2
3 4