Stack Overflow
Stack Overflow

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

Is it possible to override Sphinx autodoc for specific functions?

I'm using Sphinx's autodoc plugin to automatically document a set of modules. I have a function that accepts *args, and I'd like to override the documentation to show the slightly nicer funcname(arg1[, arg2[, ...]]) style that the Python stdlib…
DNS
  • 37,249
  • 18
  • 95
  • 132
14
votes
1 answer

How can I show inherited members of a class in my Sphinx documentation?

I want to document some classes which all derive from the same base class with some common attributes and I would like to repeat the documentation for every attribute in the subclasses, so that I can see all the attributes for a class in a single…
Kjir
  • 4,437
  • 4
  • 29
  • 34
14
votes
1 answer

Sphinx autodoc show-inheritance: How to skip undocumented, intermediate bases?

I have a three-layered class structure like this: class Super(object): """This class is documented.""" class Intermediate(Super): pass class Sub(Intermediate): """This is also documented.""" My index.rst file looks as follows: ..…
Michael Herrmann
  • 4,832
  • 3
  • 38
  • 53
13
votes
2 answers

Is OptionParser in conflict with Sphinx?

I'm trying to write a documentation for my project in Sphinx and whenever Sphinx encounters OptionParser in my module it gives me: sphinx-build: error: no such option: -b I thought that it's impossible, so I wrote a simple module to check…
Michal
  • 6,411
  • 6
  • 32
  • 45
13
votes
1 answer

sphinx severe: unexpected section title -- arbitrary headings in function docstring

Using autodoc and similar tools allows one to compile documentation from source docstrings. It doesn't however, seem to allow arbitrary ReST section titles in function or class docstrings, and produces the error: SEVERE: Unexpected section title. I…
user2561747
  • 1,333
  • 2
  • 16
  • 39
13
votes
3 answers

How can I provide Sphinx documentation for a namedtuple (with autodoc)?

I am trying to document a Python project with Sphinx, but I'm having trouble combining the autodoc extension with a namedtuple generated class. In one document, gammatone.rst, I have: :mod:`gammatone` -- gammatone filterbank…
detly
  • 29,332
  • 18
  • 93
  • 152
12
votes
3 answers

sphinx.ext.autodoc: Keeping names of constants in signature

I'm using Sphinx's autodoc feature to document my API. Example: DEFAULT_OPTION = 'default' def do_something(msg, option=DEFAULT_OPTION): print msg The generated documentation now shows the following signature: do_something(msg,…
Sebastian
  • 1,055
  • 9
  • 27
12
votes
1 answer

How to include docstrings/comments located in a module, but outside of class and methods in Sphinx

I have a utils module in my package. It consists of several misc standalone methods that do not require instantiation. I would like to place some generic comments/docstring inside this utils file, such as: import os import json """ Miscellaneous…
Shailesh Appukuttan
  • 770
  • 8
  • 19
12
votes
1 answer

Autodoc params?

I'm newbie using sphinx. It looks pretty good. I have almost documented all my project using autodoc, but I want to change one behavior. Reading the documentation, I've seen this: autodoc_member_order, and want to change to 'bysource' value, the…
slothy
  • 363
  • 1
  • 3
  • 13
12
votes
2 answers

Ignore some modules in autodoc

I'm trying to use autodoc for selected modules only. I've created a file which includes: .. automodule:: some.specific.module :members: And it gets generated correctly. Unfortunately autodoc keeps trying to parse other files too (and fails…
viraptor
  • 33,322
  • 10
  • 107
  • 191
12
votes
1 answer

What is this "generated" option in Sphinx autosummary directive?

I'm using sphinx-apidoc and autosummary extensions to document an API for a library and I'm really unable to understand the purpose of the generated/ option below: .. autosummary:: :nosignatures: :toctree: generated/ module.function_1 …
Dashing Adam Hughes
  • 1,522
  • 1
  • 13
  • 12
12
votes
1 answer

Override function declaration in autodoc for sphinx

I have a module that goes something like this: #!/usr/bin/env python #: Documentation here. #: blah blah blah foobar = r'Some really long regex here.' def myfunc(val=foobar): '''Blah blah blah''' pass ...and I have a .rst file that goes…
Michael0x2a
  • 58,192
  • 30
  • 175
  • 224
12
votes
1 answer

Omit (or format) the value of a variable when documenting with Sphinx

I'm currently documenting a whole module with autodoc. However, I define several variables on the module level that contain long lists or dicts. They are included in the documentation together with the values, and the values are unformatted, so it…
Lev Levitsky
  • 63,701
  • 20
  • 147
  • 175
11
votes
2 answers

Why is sphinx automodule not showing any module members?

I started working on a python module and wanted to document the code "in place". So i set up sphinx in a subdirectory with sphinx-quickstart resulting in this directory structure (only the files i edited are…
lalu
  • 331
  • 1
  • 3
  • 10
11
votes
1 answer

Show *only* docstring in Sphinx documentation?

Sphinx has a feature called automethod that extracts the documentation from a method's docstring and embeds that into the documentation. But it not only embeds the docstring, but also the method signature (name + arguments). How do I embed only the…
Sridhar Ratnakumar
  • 81,433
  • 63
  • 146
  • 187
1 2
3
…
30 31