Configuration Documentation

The library provides three Sphinx directives:

1. setup-config-example - Generates (and validates) an example configuration file in YAML format for a given ConfigurationStep. This includes information about field names, possible values, default values, and descriptions, helping clients understand available configuration options.

2. setup-config-usage - Generates basic usage information and lists all configured steps with metadata and example YAMLs (it does this by wrapping setup-config-example so the examples will be validated as well). This provides a complete overview for users who want to bootstrap their installation.

3. validate-config-example - Validates a given YAML configuration example for a given ConfigurationStep and displays the YAML configuration in a code block.

Using setup-config-example

First, add the extension and its requirements to conf.py in your documentation directory:

extensions = [
    ...
    "sphinx.ext.autodoc",
    "django_setup_configuration.documentation.setup_config_example",
    ...
]

Then display a YAML example using the directive:

.. setup-config-example:: path.to.your.ConfigurationStep

This will produce output similar to the following example (using the SitesConfigurationStep provided by this library):

sites_config_enable: true
sites_config:

  # REQUIRED: true
  items:
    -

      # REQUIRED: true
      domain: example_string

      # REQUIRED: true
      name: example_string

Warning

Not all configurations are currently supported by this directive. Complex type annotations like list[ComplexObject | ComplexObject] will raise errors during documentation build.

Using setup-config-usage

First, add the extension and its requirements to conf.py in your documentation directory:

extensions = [
    ...
    "sphinx.ext.autodoc",
    "django_setup_configuration.documentation.setup_config_example",
    "django_setup_configuration.documentation.setup_config_usage",
    ...
]

To use this directive, you’ll also have to ensure Django is configured and initialized in your Sphinx conf.py file, for instance like this:

# docs/conf.py

# ...
import django
from django.conf import settings

os.environ.setdefault("DJANGO_SETTINGS_MODULE", "your_settings_module")
django.setup()

# ...
# extensions = [...]

Then display usage information using the directive:

.. setup-config-usage::

This generates a “how to” introduction for invoking the management command, followed by sections for each configured step with example YAML configurations.

By default, the directive will output a full documentation page, but you can hide individual sections using the following options:

• show_command_usage: whether to include basic usage information on how to invoke the management command

• show_steps: whether to display information about the configured steps

• show_steps_toc: whether to include a short table of contents of all configured steps, before displaying the individual step sections

• show_steps_autodoc: whether to include an autodoc section showing the full path to the step module

For example, to hide the usage section, show the steps without autodoc:

.. setup-config-usage::
    :show_command_usage: false
    :show_steps_autodoc: false

Note

The titles for the step sections will be taken from the step’s verbose_title field, whereas the descriptions are taken from the step class’s docstring (if present).

Using validate-config-example

If the generated examples are not enough and you would like to include more specific examples in your documentation, you can use the validate-config-example directive to pass your own examples, which are automatically validated for the given ConfigurationStep by the directive.

First, add the extension and its requirements to conf.py in your documentation directory:

extensions = [
    ...
    "sphinx.ext.autodoc",
    "django_setup_configuration.documentation.validate_config_example",
    ...
]

Then display a YAML example using the directive (in the example of the SitesConfigurationStep):

.. validate-config-example:: django_setup_configuration.contrib.sites.steps.SitesConfigurationStep

    sites_config_enable: true
    sites_config:
      items:
        - domain: example-domain.localhost
          name: Example Domain

The output will be a code block with the passed YAML configuration:

sites_config_enable: true
sites_config:
  items:
    - domain: example-domain.localhost
      name: Example Domain