Autodoc Lt

[Debra Necochea]

Forthis to work, the docstrings must of course be written in correctreStructuredText. You can then use all of the usual Sphinx markup in thedocstrings, and it will end up correctly in the documentation. Together withhand-written documentation, this technique eases the pain of having to maintaintwo locations for documentation, while at the same time avoidingauto-generated-looking pure API documentation.

If you prefer NumPy or Google style docstrings over reStructuredText,you can also enable the napoleon extension.napoleon is a preprocessor that converts yourdocstrings to correct reStructuredText before autodoc processes them.

autodoc analyses the code and docstrings by introspection afterimporting the modules. For importing to work, you have to make sure that yourmodules can be found by Sphinx and that dependencies can be resolved (if yourmodule does import foo, but foo is not available in the python environmentthat Sphinx runs in, your module import will fail).

Use an environment that contains your package and Sphinx. This can e.g. be yourlocal dev environment (with an editable install), or an environment in CI inwhich you install Sphinx and your package. The regular installation processensures that your package can be found by Sphinx and that all dependencies areavailable.

autodoc provides several directives that are versions of the usualpy:module, py:class and so forth. On parsing time, theyimport the corresponding module and extract the docstring of the given objects,inserting them into the page source under a suitable py:module,py:class etc. directive.

Another example; If your class Foo has __str__ special method andautodoc directive has both inherited-members and special-members,__str__ will be documented as in the past, but other special methodthat are not implemented in your class Foo.

The automodule, autoclass andautoexception directives also support a flag option calledshow-inheritance. When given, a list of base classes will be insertedjust below the class signature (when used with automodule, thiswill be inserted for every class that is documented in the module).

All autodoc directives support the no-index flag option that has thesame effect as for standard py:function etc. directives: noindex entries are generated for the documented object (and allautodocumented members).

In an automodule directive with the members option set, onlymodule members whose __module__ attribute is equal to the module nameas given to automodule will be documented. This is to preventdocumentation of imported classes or functions. Set theimported-members option if you want to prevent this behavior anddocument all available members. Note that attributes from imported moduleswill not be documented, because attribute documentation is discovered byparsing the source file of the current module.

autodata and autoattribute support the annotationoption. The option controls how the value of variable is shown. If specifiedwithout arguments, only the name of the variable will be printed, and its valueis not shown:

For module data members and class attributes, documentation can either be putinto a comment with special formatting (using a #: to start the commentinstead of just #), or in a docstring after the definition. Commentsneed to be either on a line of their own before the definition, orimmediately after the assignment on the same line. The latter form isrestricted to one line only.

If you document decorated functions or methods, keep in mind that autodocretrieves its docstrings by importing the module and inspecting the__doc__ attribute of the given function or method. That means that ifa decorator replaces the decorated function with another, it must copy theoriginal __doc__ to the new function.

This value selects if automatically documented members are sortedalphabetical (value 'alphabetical'), by member type (value'groupwise') or by source order (value 'bysource'). The default isalphabetical.

This value is a list of autodoc directive flags that should be automaticallyapplied to all autodoc directives. The supported flags are 'members','undoc-members', 'private-members', 'special-members','inherited-members', 'show-inheritance', 'ignore-module-all'and 'exclude-members'.

If this boolean value is set to True (which is the default), autodoc willlook at the first line of the docstring for functions and methods, and if itlooks like a signature, use the line as the signature and remove it from thedocstring content.

This value contains a list of modules to be mocked up. This is useful whensome external dependencies are not met at build time and break the buildingprocess. You may only specify the root package of the dependenciesthemselves and omit the sub-modules:

This value controls the behavior of sphinx-build --fail-on-warningduring importing modules.If False is given, autodoc forcedly suppresses the error if the importedmodule emits warnings. By default, True.

Return a listener that either keeps, or if exclude is True excludes,lines between lines that match the marker regular expression. If no linematches, the resulting docstring would be empty, so no change will be madeunless keepempty is true.

If more than one enabled extension handles the autodoc-skip-memberevent, autodoc will use the first non-None value returned by a handler.Handlers should return None to fall back to the skipping behavior ofautodoc and other enabled extensions.

sphinx-quickstart rapidly fires a series of prompts, the defaults are typically sensible, but enable autodoc when prompted. intersphinx might be useful if you have projects whose documentation may cross-reference eachother. viewcode adds links to source code from module listings, which could be helpful to end users. Make good use of the provided Makefile.

Assuming you enabled the autodoc extension, Sphinx can be set-up to automatically build a nice module index (such as the one found on the Goldilocks documentation) with links to documentation generated from the docstrings of your modules and classes; which is both pretty and a nice excuse to document your code properly too.

Be sure to set the -o outputdir that will contain the generated Sphinx source files to source/. This took me a while to figure out, but without it (say just dumping everything into the docs/ directory), the py-modindex.html file would not be generated when built by ReadTheDocs and would thus be missing, causing a 404 on the website3. sourcedir (which is more sensibly called module_path in the Sphinx documentation) should point to your Python package (e.g. ../)4.

Sphinx is configured by a conf.py that sits in the docs/ directory. The majority of important configuration options have already been set for you by sphinx-quickstart but here are a couple of things that I typically alter:

At the time of writing, the default theme is alabaster, rocked by various projects including the glorious requests package. However I actually like the ReadTheDocs default theme (other themes are available) and alter the html_theme accordingly:

To ensure that sphinx-build can import your package and generate some lovely API documentation (and that all important module index; py-modindex), simply uncomment this line near the top of conf.py and those warnings should disappear on your next attempt at make html:

I find reStructuredText kinda grim for docstrings, so I use the sphinx-napoleon extension. This allows you to write numpy or Google style docstrings instead of dense blocks of quite difficult to read RST. As of Sphinx 1.3, the extension no longer needs to be manually installed and can be enabled in the same way as other extensions, like the autodoc:

Sphinx has a really nifty feature where one can reference classes, functions and the like anywhere in your documentation (even docstrings, too), and it will generate a link to the relevant part of the documentation. However I always forget the syntax, and what this feature is called. Turns out, this is referencing domains in Sphinx terminology and the syntax for each domain is well documented on this page that I just have to keep finding.

Before Sphinx 1.3, one had to install the sphinx-napoleon extension separately. Although this is no longer the case, you might find yourself wondering how to get custom plugins and the like to work with your ReadTheDocs documentation instance in future:

always_use_bars_union (default: False): If True, display Union's using the operator described in PEP 604.(e.g X Y or int None). If False, Unions will display with the typing in brackets. (e.g. Union[X, Y]or Optional[int])

typehints_use_rtype (default: True): Controls behavior when typehints_document_rtype is set to True. IfTrue, document return type in the :rtype: directive. If False, document return type as part of the :return:directive, if present, otherwise fall back to using :rtype:. Use in conjunction withnapoleon_use_rtypeto avoid generation of duplicate or redundant return type information.

simplify_optional_unions (default: True): If True, optional parameters of type "Union[...]" are simplifiedas being of type Union[..., None] in the resulting documentation (e.g. Optional[Union[A, B]] -> Union[A, B,None]). If False, the "Optional"-type is kept. Note: If False, any Union containing None will bedisplayed as Optional! Note: If an optional parameter has only a single type (e.g Optional[A] or Union[A, None]),it will always be displayed as Optional!

typehints_formatter (default: None): If set to a function, this function will be called with annotation as firstargument and sphinx.config.Config argument second. The function is expected to return a string with reStructuredTextcode or None to fall back to the default formatter.

The extension listens to the autodoc-process-signature and autodoc-process-docstring Sphinx events. In the former,it strips the annotations from the function signature. In the latter, it injects the appropriate :type argname: and:rtype: directives into the docstring.

To use sphinx.ext.napoleon with sphinx-autodoc-typehints, makesure you load sphinx.ext.napoleon first, beforesphinx-autodoc-typehints. See Issue 15 on the issuetracker for more information.

3a8082e126