Jakski's blog

While most of times it's sufficient to just comment your roles in README, it may be useful to maintain documentation generated automatically from variables descriptions. This guide shows how to scaffold role with Sphinx configuration to automatically generate UNIX manual pages.

Sphinx setup

We will need Sphinx and 2 extensions:

• sphinxcontrib-lookup-yaml to automatically fetch default values for variables from YAML files in documentation
• sphinxcontrib-autoyaml to convert YAML-style docstrings into documentation

$ pip3 install sphinx \
              sphinxcontrib-autoyaml \
              sphinxcontrib-lookup-yaml

Create basic Sphinx configuration in directory with role:

$ sphinx-quickstart

Plug extensions and adjust configuration in conf.py:

import re

def get_latest_version(changelog):
  '''Retrieve latest version of package from changelog file.'''
  # Match strings like "## [1.2.3] - 2017-02-02"
  regex = r'^##\s*\[(\d+.\d+.\d+)\]\s*-\s*\d{4}-\d{2}-\d{2}$'
  with open(changelog, 'r') as changelog:
      content = changelog.read()
  return re.search(regex, content, re.MULTILINE).group(1)

extensions = [
 'sphinxcontrib.lookup_yaml',
 'sphinxcontrib.autoyaml'
]
autoyaml_root = '.'
lookup_yaml_root = '.'
exclude_patterns = ['docs', 'Thumbs.db', '.DS_Store']
source_suffix = '.rst'
master_doc = 'DOCS'
version = get_latest_version('CHANGELOG')

Change destination directory in Makefile:

BUILDDIR      = docs

Fill CHANGELOG with information about first release:

## [0.0.1] - 2018-06-02
### Added
- First release.

Using documentation extensions

Create basic DOCS.rst with variable documentation fetched from YAML file:

role_name
================================================================================

Role description

Requirements
--------------------------------------------------------------------------------

Role requirements

Variables
--------------------------------------------------------------------------------

.. autoyaml:: defaults/main.yml

Examples
--------------------------------------------------------------------------------

Code blocks with examples

License
--------------------------------------------------------------------------------

MIT

Author
--------------------------------------------------------------------------------

Your name <your@mail>

Test setup with example variable in defaults/main.yml:

---
### example_var
#   This is example variable to test documentation generation.
#
#   Default:
#
#   .. lookup-yaml:: defaults/main.yml
#
#      example_var
example_var: some_value

Building

Generate manual pages with GNU Make:

$ make man

Read compiled documentation:

$ man ./docs/man/*.1