|tags:||documentation, docs, developer|
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.
A blueprint for this proposal can be found at:
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:
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:
We could not do this documentation, leaving the repository as is.
There should be no impact on the playbooks; this change only adds files outside of the playbooks.
This documentation will have to be kept up-to-date with releases. Since documentation is an on-going process, it falls to reviewers to enforce documentation updates to playbook changes.
Since this change is not to the playbooks or scripts, it should have no security impact.
This will not have a production performance impact. I do propose adding a docs build job to the gating process, which would extend gating job times by some unknown amount.
Users of a deployed cloud would likely never see this change. It’s largely targeted at developers of this project or deployers.
There should be little to no deployer impact. This documentation will be for developers, mostly, but deployers may be able to use it as reference for running scripts and tools on their deployment.
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.
This change does not depend on any other blueprints or specs. It can be done largely in parallel with other projects and issues.
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.
Other contributors are welcome to work on the mentioned sections.
This change will add a Sphinx build job to the gating process. The Sphinx build job should not run on changes that have no affected docs files.
The Sphinx documentation build job should succeed for the change to merge.
As mentioned above, this will create a new docs repo that the docs team can then build more detailed documentation in reference to.