Currently, the openstack-ansible repository does not have any cohesive
developer documentation. This proposal aims to begin such documentation,
providing a overview and reference for new contributors.

Documentation covered in this proposal is not intended to be exhaustive.

Also, documentation is a constantly shifting thing - this proposal is just
intended to get the initial documents created; documentation maintenance
falls outside of scope. Reviewers should help make sure patches adequately
update associated documentation.

Currently, when new contributors come to the repository, there isn’t much to
help them to understand the general structure of the project. Currently, there
is the development-stack.rst file, which provides a very brief introduction
to getting an all-in-one (AIO) install started, as well as tearing down
an environment, but there’s not much else. This can be intimidating for
newcomers, as well as current contributors who might forget details of
some portion of the large code base.

This proposal recommends making a new docs repo, which would contain Sphinx
documentation on the following documentation:

Overview of doing deployments using openstack-ansible

Variable files, for knowing which variable files are used where in the process.

Scripts. This section will cover using bootstrap, gating, and teardown
scripts. It might also document some of the important variables/parameters
for these scripts. The openstack-ansible wrapper would be nice to cover
here and in the extending section.

Repository role/playbook. Since the repository is fairly unique to
openstack-ansible, this should be probably be a bit more detailed than
the rest of the of the documentation. The openstack_services.yml and
openstack_other.yml files are of particular interest here.

Inventory management. This section should discuss the dynamic_inventory.py
file and and the inventory_management.py files.

Extending openstack-ansible. This would cover using the conf.d and env.d
directories, as well as user_extras.yml files. Changes to ansible.cfg
necessary might be useful, too.

Also, the docs directory should be built by Sphinx on a regular basis,
preferably at the gate.

Some topics are explicitly out of scope for this changes. In particular:

Host networking setup. This is highly individualized per environment, and
too broad to cover here.

Individual roles. The individual roles should not be documented as part of
this. There are too many roles and too many changes to be able to keep up with
those changes at the openstack-ansible level.

End user documentation. For this specification, the ‘end user’ is a deployer
or user of the deployed OpenStack system. The installation guide, operations
guide, and user/admin guides are all out of scope.

This documentation will be targeted mostly at developers in the hope that it
will be easier for new contributors to understand how the project works and
where to start. This can also be useful as a reference for existing developers.

The Sphinx build process may add some overhead, since developers should build
the documentation before pushing their changes.

Where this proposal differs from the CONTRIBUTING.txt is the focus -
CONTRIBUTING.txt is largely about the process around getting changes into the
codebase. In contrast, the docs directory should cover technical information
about how to use the repository.

As described earlier, this will be implemented with ReST files in a docs
directory at the root of the repo. Also, there will be a dependency on
Sphinx in the dev-requirements, and a script added to run the Sphinx docs
build job a tthe gate.