In part 1 I talked about the files that are required in the base of your new role repository. I'll go into information on setting up the required directories that are not specific to Ansible itself.

/doc directory

This directory contains all the files required to build the Sphinx documentation. In terms of a base there isn't too much - so depending on the role you can fill in more details.

Makefile - This is the Sphinx Makefile. You can copy it over from the Sphinx repo and or another OSA role.

requirements.txt - The pip requirements for building the docs, I'd recommend just copying this from an existing role. The OpenStack requirements project handles automatic requirements updates, so once your new role is official it will receive updates to the requirements file automatically.

source/conf.py - The documentation configuration file, a sample can be seen here. It's easier to copy this from an existing role - although the file is quite well commented so take a look inside. There is a reference to the role name that you should fix up.

source/index.rst - The index file. This is specified inside your conf.py, but if you copied it over the default is index. This file defines the initial index when going to the role documentation. You can put a placeholder in there, but writing your docs whilst creating the role is super important! Take a look at some other roles for examples on how to structure that.

/examples directory

One standard that exists across the majority of roles in OSA is the examples directory with an example playbook. This can be pretty simple, and isn't technically required. Additionally, make sure to include any files you do create in the examples directory into your doc/source/index.rst file. This is a good way to document what a playbook should look like to include the new role.

/meta directory

This is an Ansible directory, but the setup of this is more scaffolding, and is done in a pretty common way in OSA. These are pretty standard, so copy over the meta/main.yml and meta/openstack-ansible.yml from an existing mature role. The fields are pretty self explanatory in both, but you will probably want to change the supported platforms:, categories: at a minimum, inside meta/main.yml, as well as any descriptions. The meta/openstack-ansible.yml file is used to define maturity and role creation time, so adjust those fields to fit. There is documentation around that process here, so you can pick the right status, and understand that process.

/releasenotes directory

Release notes are another arrow in the documentation quiver (yes even I cringed after that sentence). The release notes use the reno tool to allow projects to create release notes to track changes that would be important to operators and deployers - alerting them of changes, new features, upgrade concerns and deprecations (amongst others).

There are 2 sub directories, the notes directory, you can more or less ignore this for now, although creating the directory is useful. This directory contains the individual release notes that you would add as you add features.

The source directory contains the configuration bits for the release notes. Inside there are several files that are required:

  • conf.py - this is another Sphinx conf.py file - I'd recommend copying this over from an existing project, but again this is quite well commented.
  • index.rst - the index file, you can again copy from an existing project, but make sure to adjust the included files removing any releases that don't exist - that would be all of them except unreleased at this point.
  • unreleased.rst - the index file for current branches release notes. Copy this over, its a pretty minimal file though.
  • _static/.placeholder & _templates/.placeholder - These are placeholder files that are blank, you can touch these to create them.

That's more or less it! We still need to cover testing and then create the role but now we should be pretty much ready to rumble, and start adding content to the documentation, and tasks/handlers/templates/default vars etc to the Ansible role itself!