# 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.

  Added 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.

  COMMA_RE = re.compile(',\\s*')
  MAX_PARTIAL_TYPED_ARG_LINES = 3
  __firstlineno__ = 170
  __init__(*args, **kwargs)

    Initialize the parser.

    Parameters:

      - *args (`tuple`) – Positional arguments for the parent.

      - **kwargs (`dict`) – Keyword arguments for the parent.

  __static_attributes__ = ()
  consume_lines(num_lines)

    Consume the specified number of lines.

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

    Added in version 1.9.

    Parameters:

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

  extra_fields_sections = [('keys', 'Keys'), ('model attributes', 'Model Attributes'), ('option args', 'Option Args'), ('tuple', 'Tuple')]
  extra_returns_sections = [('context', 'Context', {}), ('type', 'Type', {'require_type': True})]
  extra_version_info_sections = [('deprecated', 'deprecated'), ('version added', 'versionadded'), ('version changed', 'versionchanged')]
  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.

    Added in version 2.0.

    Parameters:

      type_str (`unicode`) – The string to parse and create references from.

    Returns:

      The new string.

    Return type:

      `unicode`

  partial_typed_arg_end_re = re.compile('\\s*(.+?)\\s*\\):$')
  partial_typed_arg_start_re = re.compile('\\s*(.+?)\\s*\\(\\s*(.*[^\\s]+)\\s*[^:)]*$')
  peek_lines(num_lines=1)

    Return the specified number of lines without consuming them.

    Added in version 1.9.

    Parameters:

      num_lines (`int`, optional) – The number of lines to return.

    Returns:

      The resulting lines.

    Return type:

      `list` of `str`

  queue_line(line)

    Queue a line for processing.

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

    Added in version 1.9.

    Parameters:

      line (`str`) – The line to queue.

  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_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.

        Added in version 2.0.

  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.

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.