Questions tagged [autodoc]

Extension for the Sphinx documentation generator that imports Python modules in order to extract docstrings in a semi-automatic way.

Python Sphinx extension that can import the modules being documented, and pull in documentation from docstrings in a semi-automatic way.

The sphix.ext.autodoc extension can be used in conjunction with the sphinx.ext.napoleon extension. This allows use of NumPy and Google style docstrings. The Napoleon prepocessor will initially convert your docstrings to ReStructured text, that afterwards is processed by autodoc.

Several commonly used directives are provided by autodoc, namely ..automodule:: and ..autoclass: For examples of use see the sphinx.ext.autodoc documentation.

See also:

456 questions
6
votes
1 answer

How to document nested classes with Sphinx's autodoc?

Is there any way to document a nested class with Sphinx's autodoc plugin? In: class A: class B: """ class B's documentation. """ # ... I want to use autoclass or something similar in my .rst file to document A.B specifically. I…
eepp
  • 7,255
  • 1
  • 38
  • 56
6
votes
2 answers

Can the Sphinx "automodule" be told to automatically insert section breaks between members?

This question is inspired by the Mayavi documentation, which has nice section breaks with the name of the function being described between each module member. My .rst right now just looks like: SQLAlchemy…
paradiso
  • 379
  • 3
  • 14
5
votes
2 answers

Controlling where sphinx generated .rst files are saved

Suppose the following documentation structure for sphinx: doc |_ _static |_ _templates |_ api |_ index.rst |_ classes.rst |_ functions.rst |_ index.rst |_ more_functions.rst |_ conf.py And that classes.rst, functions.rst and…
Mathieu
  • 5,410
  • 6
  • 28
  • 55
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
1 answer

How to make Sphinx autodoc extension include an underscore/private Python module

I am autogenerating documentation for a Python package using Sphinx with the autodoc extension. The issue I am facing is that the autodoc skips any modules with an underscore. Some modules were underscored to discourage users from importing them.…
hamaney
  • 454
  • 7
  • 16
5
votes
1 answer

Sphinx not documenting complex Enum classes

In my code I have some classes that are complex Enum types. For example: class ComplexEnum(SomeOtherClass, Enum): """ Some documentation """ MEMBER1 = SomeOtherClass(1) MEMBER2 = SomeOtherClass(2) def __init__(self, arg): …
Rittel
  • 579
  • 5
  • 21
5
votes
1 answer

Using Jinja2 with Sphinx autosummary

I am trying to use sphinx.ext.autosummary to document a Python package. Since 'autosummary' requires us to list all the items to be included, I wanted to specify these using Jinja2. My conf.py is as follows (relevant parts shown): extensions = [ …
5
votes
0 answers

Shorten long type names in autodoc

When autodoc lists a type in the documentation it generates, such as the Bases that a class inherits from, or type hints for a function parameters, it adds the type's module. For example, a function receiving a Tensorflow Optimizer would be listed…
Roy Fox
  • 313
  • 1
  • 3
  • 5
5
votes
1 answer

Sphinx autodoc and multi-line strings

I have a python module which defines a multi-line string constant. I want to have the multi-line string display nicely in the Sphinx-based documentation. Below, is some example Python code, RST, and how it renders with sphinx-build. However, I would…
Manuel
  • 6,461
  • 7
  • 40
  • 54
5
votes
1 answer

How to exclude pytest test_* functions from Sphinx autodoc?

I have multiple modules in my package. package/ |--mod1.py |--mod2.py Each module contains some functions and a test_function for testing the module. I am using sphinx-apidoc to generate the .rst files for every module in package. My problem is…
Shubham Vasaikar
  • 698
  • 9
  • 23
5
votes
1 answer

how to make apidocs use packages instead of modules in sphinx-apidoc

I'm using docstrings to document python code and sphinx-autodoc to generate apidoc HTMLs. The structure of my packages is as follows: mainpackage.subpackage.module, I want apidocs to link to classes from a module as mainpackage.subpackage.Class and…
niedakh
  • 2,819
  • 2
  • 20
  • 19
5
votes
2 answers

Why Sphinx do not autodoc module variables?

I want to have automatic documentation for module variables, but it just not work. All variables is missing in the doc... How can I fix this, so autodoc will list every module variable? mypackage/__init__.py: class __init__: test = 'test' …
user2081554
5
votes
2 answers

autodoc a class that extends a mocked class

I'm trying to run autodoc over a class that extends an external class. I've used mock so that the import is accepted. For that I used what was described in this blog…
whoWho
  • 79
  • 4
5
votes
3 answers

How do I avoid "SEVERE: Duplicate ID" warnings for my autodoc'd modules in Sphinx?

I'm using rST/Sphinx to document my Python, however when building it's throwing warnings such as ...Code/doc/code.rst:3: SEVERE: Duplicate ID: "module-toast". My Python source files are documented like so: #!/usr/bin/env python ''' .. module::…
Nick T
  • 25,754
  • 12
  • 83
  • 121
4
votes
0 answers

Is it possible to set Sphinx autodoc module path from Jupyter Book?

Is it possible to set the Sphinx autodoc Python module path from Jupyter Book, for example via _config.yml? I'm using Jupyter Book to document a Python system and publish to Read The Docs. I can set the module path from Sphinx by adding code like…