sphinxcontrib-autodoc-filterparams 0.0.1

A sphinx extension to filter parameters from documentation

Although it might usually be a symptom of poor architecture, sometimes you really want to exclude function parameters from your Sphinx documentation.

This extension does just that.

Usage

• Add it to your conf.py extension list, typically immediately after the entry for sphinx.ext.autodoc. If you use something like the napoleon extension to re-format docstrings, then add it immediately after that.

• Declare a function called sphinxcontrib_autodoc_filterparams.

Example

The following would hide all parameters whose names starts with an underscore:

extensions = [
    'sphinx.ext.autodoc',
    'sphinxcontrib_autodoc_filterparams'
]

def sphinxcontrib_autodoc_filterparams(fun, param):
    return not param.startswith('_')

The callback takes two arguments, the current function and parameter, and it should return a boolean indicating whether or not to keep the parameter.

A slightly more elaborate example looks at the function context as well as the name of the parameter:

exclude_params = {
    'my_package.my_module.MyClass.my_method': {'**kwargs'}
}

def sphinxcontrib_autodoc_filterparams(fun, param):
    exclude = exclude_params.get(fun.__module__ + '.' + fun.__qualname__)
    return exclude is None or param not in exclude

Options

sphinxcontrib_autodoc_filterparams

The callback function, invoked for each function parameter. If this function returns True then the parameter will be documented, otherwise it will be excluded.

sphinxcontrib_autodoc_filterparams_stars

A boolean indicating whether or not asterisks should be prepended to parameter names when invoking the callback (one star for variadic positional, two stars for variadic keyword). Default is True.