Skip to main content

A sphinx extension to filter parameters from documentation

Project description

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.

Project details


Release history Release notifications

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Files for sphinxcontrib-autodoc-filterparams, version 0.0.1
Filename, size File type Python version Upload date Hashes
Filename, size sphinxcontrib_autodoc_filterparams-0.0.1-py3-none-any.whl (4.8 kB) File type Wheel Python version py3 Upload date Hashes View hashes
Filename, size sphinxcontrib_autodoc_filterparams-0.0.1.tar.gz (3.2 kB) File type Source Python version None Upload date Hashes View hashes

Supported by

Elastic Elastic Search Pingdom Pingdom Monitoring Google Google BigQuery Sentry Sentry Error logging AWS AWS Cloud computing DataDog DataDog Monitoring Fastly Fastly CDN DigiCert DigiCert EV certificate StatusPage StatusPage Status page