Documenting collections

Documenting modules and plugins

Documenting modules is thoroughly documented in Module format and documentation. Plugins can be documented the same way as modules, that is with DOCUMENTATION, EXAMPLES, and RETURN blocks.

Documenting roles

To document a role, you have to add a role argument spec by creating a file meta/argument_specs.yml in your role. See Role argument validation for details. As an example, you can look at the argument specs file of the sensu.sensu_go.install role on GitHub.

Verifying your collection documentation

You can use antsibull-docs to lint your collection documentation. See Linting collection documentation. for details.

Build a docsite with antsibull-docs

You can use antsibull-docs to build a Sphinx-based docsite for your collection:

  1. Create your collection and make sure you can use it with ansible-core by adding it to your COLLECTIONS_PATHS.

  2. Create a directory dest and run antsibull-docs sphinx-init --use-current --dest-dir dest namespace.name, where namespace.name is the name of your collection.

  3. Go into dest and run pip install -r requirements.txt. You might want to create a venv and activate it first to avoid installing this globally.

  4. Then run ./build.sh.

  5. Open build/html/index.html in a browser of your choice.

See antsibull-docs documentation for complete details.

If you want to add additional documentation to your collection next to the plugin, module, and role documentation, see docs directory.