# 2018-06-26 Documenting Ansible roles

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
```