Using the Sphinx extension

No one likes to spend hours updating configuration documentation. Often, it’s accidentally forgotten or overlooked when maintaining a project.

No one likes to spend hours trying to get something to work only to discover the configuration documentation is out of date, missing important information, or just wrong.

Blech.

Everett comes with a Sphinx extension to make it easier to document Everett components and configuration. This allows you to write configuration code and have it automatically documented in your Sphinx-generated docs without having to manually update it.

Further, Everett components will show up in the index making it easier for users to find what they’re looking for.

Contains the autocomponent Sphinx extension for auto-documenting components with configuration.

The autocomponent declaration will pull out the class docstring as well as configuration requirements, throw it all in a blender and spit it out.

To configure Sphinx, add 'everett.sphinxext' to the extensions in conf.py:

extensions = [
    ...
    'everett.sphinxext'
]

Note

You need to make sure that Everett is installed in the environment that Sphinx is being run in.

Use it like this in an .rst file to document a component:

.. autocomponent:: collector.ext.s3.S3CrashStorage

You can refer to that component in other parts of your docs and get a link by using the :everett:component: role:

Check out the :everett:component:`collector.ext.s3.S3CrashStorage`
configuration.

If your component class names are unique, then you can probably get away with:

Check out the :everett:component:`S3CrashStorage` configuration.

Changed in version 0.9: In Everett 0.8 and prior, the extension was in the everett.sphinx_autoconfig module and the directive was .. autoconfig::.

Showing docstring and content

If you want the docstring for the class, you can specify :show-docstring::

.. autocomponent:: collector.external.boto.crashstorage.BotoS3CrashStorage
   :show-docstring:

If you want to show help, but from a different attribute than the docstring, you can specify any class attribute:

.. autocomponent:: collector.external.boto.crashstorage.BotoS3CrashStorage
   :show-docstring: __everett_help__

You can provide content as well:

.. autocomponent:: collector.external.boto.crashstorage.BotoS3CrashStorage

   This is some content!

New in version 0.5.

Hiding the class name

You can hide the class name if you want:

.. autocomponent:: collector.external.boto.crashstorage.BotoS3CrashStorage
   :hide-classname:

This is handy for application-level configuration where you might not want to confuse users with how it’s implemented.

New in version 0.5.

Prepending the namespace

If you have a component that only gets used with one namespace, then it will probably help users if the documentation includes the full configuration key with the namespace prepended.

You can do that like this:

.. autocomponent:: collector.external.boto.crashstorage.BotoS3CrashStorage
   :namespace: crashstorage

Then the docs will show keys like crashstorage_foo rather than just foo.

New in version 0.8.

Showing keys as uppercased or lowercased

If your project primarily depends on configuration from OS environment variables, then you probably want to document those variables with the keys shown as uppercased.

You can do that like this:

.. autocomponent:: collector.external.boto.crashstorage.BotoS3CrashStorage
   :case: upper

If your project primarily depends on configuration from INI files, then you probably want to document those variables with keys shown as lowercased.

You can do that like this:

.. autocomponent:: collector.external.boto.crashstorage.BotoS3CrashStorage
   :case: lower

New in version 0.8.