beanbag_docutils.sphinx.ext.autodoc_utils¶

Sphinx extension to add utilities for autodoc.

This enhances autodoc support for Beanbag’s docstring format and to allow for excluding content from docs.

Beanbag’s Docstrings¶

By setting napoleon_beanbag_docstring = True in conf.py, and turning off napoleon_google_docstring, Beanbag’s docstring format can be used.

This works just like the Google docstring format, but with a few additions:

A new Context: section to describe what happens within the context of a context manager (including the variable).
New Model Attributes: and Option Args: sections for defining the attributes on a model or the options in a dictionary when using JavaScript.
New Deprecated:, Version Added:, and Version Changed: sections for defining version-related information.
Parsing improvements to allow for wrapping argument types across lines, which is useful when you have long module paths that won’t fit on one line.

This requires the sphinx.ext.napoleon module to be loaded.

Excluding Content¶

A module can define top-level __autodoc_excludes__ or __deprecated__ lists. These are in the same format as __all__, in that they take a list of strings for top-level classes, functions, and variables. Anything listed here will be excluded from any autodoc code.

__autodoc_excludes__ is particularly handy when documenting an __init__.py that imports contents from a submodule and re-exports it in __all__. In this case, autodoc would normally output documentation both in __init__.py and the submodule, but that can be avoided by setting:

__autodoc_excludes = __all__

Excludes can also be defined globally, filtered by the type of object the docstring would belong to. See the documentation for autodoc-skip-member for more information. You can configure this in conf.py by doing:

autodoc_excludes = {
    # Applies to modules, classes, and anything else.
    '*': [
        '__annotations__',
        '__dict__',
        '__doc__',
        '__module__',
        '__weakref__',
    ],
    'class': [
        # Useful for Django models.
        'DoesNotExist',
        'MultipleObjectsReturned',
        'objects',

        # Useful forms.
        'base_fields',
        'media',
    ],
}

That’s just an example, but a useful one for Django users.

By default, autodoc_excludes is set to:

autodoc_excludes = {
    # Applies to modules, classes, and anything else.
    '*': [
        '__dict__',
        '__doc__',
        '__module__',
        '__weakref__',
    ],
}

If overriding, you can set '__defaults__': True to merge your changes in with these defaults.

Changed in version 2.0: Changed from a default of an empty dictionary, and added the __defaults__ option.

Setup¶

Changed in version 2.0: Improved setup by enabling other default extensions and options when enabling this extension.

To use this, add the extension in conf.py:

extensions = [
    ...
    'beanbag_docutils.sphinx.ext.autodoc_utils',
    ...
]

This will automatically enable the sphinx.ext.autodoc, sphinx.ext.intersphinx, and sphinx.ext.napoleon extensions, and enable the following autodoc options:

autodoc_member_order = 'bysource'
autoclass_content = 'class'
autodoc_default_options = {
    'members': True,
    'special-members': True,
    'undoc-members': True,
    'show-inheritance': True,
}

These default options can be turned off by setting use_beanbag_autodoc_defaults=False.

Configuration¶

autodoc_excludes

Optional global exclusions to apply, as shown above.

napoleon_beanbag_docstring

Set whether the Beanbag docstring format should be used.

This is the default as of beanbag-docutils 2.0.

use_beanbag_autodoc_defaults

Set whether autodoc defaults should be used.

New in version 2.0.

Functions

setup(app)

Set up the Sphinx extension.

Classes

BeanbagDocstring(*args, **kwargs)

Docstring parser for the Beanbag documentation.

class beanbag_docutils.sphinx.ext.autodoc_utils.BeanbagDocstring(*args, **kwargs)¶

Bases: GoogleDocstring

Docstring parser for the Beanbag documentation.

This is based on the Google docstring format used by Napoleon, but with a few additions:

Support for describing contexts in a context manager (using the Context: section, which works like Returns or Yields).
Model Attributes: and Option Args: argument sections.
Parsing improvements for arguments to allow for wrapping across lines, for long module paths.

partial_typed_arg_start_re = re.compile('\\s*(.+?)\\s*\\(\\s*(.*[^\\s]+)\\s*[^:)]*$')¶

partial_typed_arg_end_re = re.compile('\\s*(.+?)\\s*\\):$')¶

extra_returns_sections = [('context', 'Context', {}), ('type', 'Type', {'require_type': True})]¶

extra_fields_sections = [('keys', 'Keys'), ('model attributes', 'Model Attributes'), ('option args', 'Option Args'), ('tuple', 'Tuple')]¶

extra_version_info_sections = [('deprecated', 'deprecated'), ('version added', 'versionadded'), ('version changed', 'versionchanged')]¶

MAX_PARTIAL_TYPED_ARG_LINES = 3¶

COMMA_RE = re.compile(',\\s*')¶

__init__(*args, **kwargs)¶

Initialize the parser.

Parameters:

*args (tuple) – Positional arguments for the parent.
**kwargs (dict) – Keyword arguments for the parent.

register_returns_section(keyword, label, options={})¶

Register a Returns-like section with the given keyword and label.

Parameters:

keyword (unicode) – The keyword used in the docs.
label (unicode) – The label outputted in the section.
options (dict, optional) –
Options for the registration.

This accepts:

Keys:

require_type (bool, optional) – Whether the type is required, and assumed to be the first line.

New in version 2.0.

register_fields_section(keyword, label)¶

Register a fields section with the given keyword and label.

Parameters:

keyword (unicode) – The keyword used in the docs.
label (unicode) – The label outputted in the section.

register_version_info_section(keyword, admonition)¶

Register a version section with the given keyword and admonition.

Parameters:

keyword (unicode) – The keyword used in the docs.
admonition (unicode) – The admonition to use for the section.

peek_lines(num_lines=1)¶

Return the specified number of lines without consuming them.

New in version 1.9.

Parameters:: num_lines (int, optional) – The number of lines to return.
Returns:: The resulting lines.
Return type:: list of str

consume_lines(num_lines)¶

Consume the specified number of lines.

This will ensure that these lines are not processed any further.

New in version 1.9.

Parameters:: num_lines (int, optional) – The number of lines to consume.

queue_line(line)¶

Queue a line for processing.

This will place the line at the beginning of the processing queue.

New in version 1.9.

Parameters:: line (str) – The line to queue.

make_type_reference(type_str)¶

Create references to types in a type string.

This will parse the string, separating out a type from zero or more suffixes (like , optional).

The type will be further parsed into a space-separated tokens. Each of those will be set as a reference, allowing Sphinx to try to link it. The exceptions are the words “of” and “or”, which we use to list optional types.

The suffixes are each formatted with emphasis.

New in version 2.0.

Parameters:: type_str (unicode) – The string to parse and create references from.
Returns:: The new string.
Return type:: unicode

beanbag_docutils.sphinx.ext.autodoc_utils.setup(app)¶

Set up the Sphinx extension.

This sets up the configuration and event handlers needed for enhancing auto-doc support.

Parameters:: app (sphinx.application.Sphinx) – The Sphinx application to register configuration and listen to events on.

beanbag_docutils.sphinx.ext.autodoc_utils¶

Beanbag’s Docstrings¶

Excluding Content¶

Setup¶

Configuration¶

Table of Contents

Previous topic

Next topic

This Page