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
2
votes
1 answer

Is there a standard format for documenting function-type parameters in Sphinx using sphinx.ext.napoleon?

I am using Sphinx to document one of my projects and one of the classes takes in a function as a parameter in its __init__. Is there a standard way to document this function-type parameter? I am also using sphinx.ext.napoleon to use Google…
Ben Soyka
  • 816
  • 10
  • 25
2
votes
1 answer

Basic syntax of comments and docstrings in Python code

I'm learning how to use Sphinx to create a documentation for my code. After I saw some examples like this: def complex(real=0.0, imag=0.0): """Form a complex number. Keyword arguments: real -- the real part (default 0.0) imag -- the…
Henrique Oliveira Costa
  • 49
  • 1
  • 1
  • 5
2
votes
1 answer

How to get the same output from sphinx napoleon and numpy style docs as with the default rst way?

If I take the very simple python file: def magic_function(parameter1): """ Do magic with parameter1. :param parameter1: The first of all paramters :type parameter1: nd_array """ return parameter1 I get the type right after…
NOhs
  • 2,780
  • 3
  • 25
  • 59
2
votes
2 answers

Can I use Sphinx automodule but drop the module name in the signature?

I have a module mod with some submodule submod and use .. automodule:: mod.submod to generate documentation for it. The signatures of the elements (functions, classes etc.) in the modules now show the qualified name, like…
kuropan
  • 774
  • 7
  • 18
2
votes
1 answer

Documenting different argument possibilities on same function

I'm using Google-style docstrings with sphinx.ext.autodoc to automatically generate documentation for my functions, and make sure they are properly self-documented in the code. I have a function def myfunc(id=None, size=None, hash=None) that returns…
toucanb
  • 523
  • 1
  • 3
  • 10
2
votes
1 answer

Unable to create documentation with Sphinx and Google docstrings

I am writing a Python API and I have documented every class and function in the sources using Google docstring convention, which I find way more readable than the Sphinx convention. I want to use Sphinx to build the documentation for my API. There…
Enaid
  • 305
  • 1
  • 18
1
vote
1 answer

Sphinx-autodoc with napoleon (Google Doc String Style): Warnings and Errors about Block quotes and indention

I am using Sphinx 4.4.0 with napoleon extension (Google Doc String). I have this two problems ARNING: Block quote ends without a blank line; unexpected unindent. ERROR: Unexpected indentation. I found something about it on the internet but can not…
buhtz
  • 10,774
  • 18
  • 76
  • 149
1
vote
0 answers

Autoappend Returns None to Sphinx Documentation

For module level functions, is there a way to auto generate content that frequently appears, namely 'Returns: None' , so that it wouldn't be repeatedly written in many docstrings? I've seen some formatting using napoleon_custom_sections, but that…
lexalenka
  • 307
  • 4
  • 16
1
vote
1 answer

Docstrings are not generated on Read the Docs with Sphinx autodoc and napoleon extensions

I am using the Sphinx autodoc and napoleon extensions to generate the documentation for my project (Qtools). This works well on my local machines. I am using Sphinx 3.1.2 (or higher). However, when I build the documentation on Read the Docs (RTD),…
Nielsen
  • 11
  • 1
1
vote
0 answers

Intersphinx Docstring Readability

Intersphinx is a very nice tool in order to put cross-references into package documentations. However, one issue is that the way these cross-references are written results in reduced legibility of the docstrings when read with help(function) in the…
Hyperplane
  • 1,422
  • 1
  • 14
  • 28
1
vote
1 answer

Adding parameters to module docstrings with Python Sphinx

I have a docstring in the beginning of every module describing its usage and functionality. Here I also want to add the most relevant parameters - like settings in a parameter file or via command line arguments. It's no classical function parameters…
monoceros84
  • 86
  • 8
1
vote
1 answer

Insert image in sphinx using napoleon pre-processor

Using sphinx 3.1.1, I want to insert an image using the napoleon pre-processor. It seems that by having the command: ".. image::" in the docstring, it prevents pre-interpretation with the napoleon pre-processor and the docstring is interpreted by…
Worldsheep
  • 163
  • 3
1
vote
1 answer

how to correctly add nested list in numpy docstring in combination with sphinx docstring

I'm wondering how I can achieve the following. I'm using the numpy docstring style in combination with sphinx autodoc to generate automated documenation. However, I'm struggeling in having a nested list in the output: Attributes ---------- attribute…
math
  • 1,868
  • 4
  • 26
  • 60
1
vote
1 answer

Sphinx fails when generating documentation for Django project

I'm trying to automatically generate documentation for my Django project using Sphinx with the autodoc and napoleon extensions. Using sphinx-quickstart I've created the following structure: MyDjangoProject ├── __init__.py ├── config │   ├──…
Oskar Persson
  • 6,605
  • 15
  • 63
  • 124
1
vote
0 answers

Some way to disable ivar auto-cross-referencing of attribute names

When using Napoleon with google docstrings (I haven't tested numpy, but I suspect similar problems) with the napoleon_use_ivar option set to True, it creates links to the names of instance variables. These names are obviously very common (things…
Nick Bastin
  • 30,415
  • 7
  • 59
  • 78
1 2
3
4