Skip to main content
Python Software Foundation 20th Year Anniversary Fundraiser  Donate today!

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


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
Filename, size sphinxcontrib_autodoc_filterparams-0.0.1.tar.gz (3.2 kB) File type Source Python version None Upload date Hashes View

Supported by

AWS AWS Cloud computing Datadog Datadog Monitoring DigiCert DigiCert EV certificate Facebook / Instagram Facebook / Instagram PSF Sponsor Fastly Fastly CDN Google Google Object Storage and Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Salesforce Salesforce PSF Sponsor Sentry Sentry Error logging StatusPage StatusPage Status page