194 lines
6.4 KiB
ReStructuredText
194 lines
6.4 KiB
ReStructuredText
openstack-ansible overview documentation
|
|
########################################
|
|
:date: 2015-04-13 13:00
|
|
: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:
|
|
|
|
https://blueprints.launchpad.net/openstack-ansible/+spec/developer-docs
|
|
|
|
Problem description
|
|
===================
|
|
|
|
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.
|
|
|
|
Proposed change
|
|
===============
|
|
|
|
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.
|
|
|
|
* Playbooks should document the high-level playbooks that prepare physical
|
|
hosts, create containers, and install OpenStack.
|
|
|
|
* 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 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.
|
|
|
|
Alternatives
|
|
------------
|
|
|
|
We could not do this documentation, leaving the repository as is.
|
|
|
|
Playbook impact
|
|
---------------
|
|
|
|
There should be no impact on the playbooks; this change only adds files
|
|
outside of the playbooks.
|
|
|
|
Upgrade impact
|
|
--------------
|
|
|
|
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.
|
|
|
|
Security impact
|
|
---------------
|
|
|
|
Since this change is not to the playbooks or scripts, it should have no
|
|
security impact.
|
|
|
|
Performance 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.
|
|
|
|
End user impact
|
|
---------------
|
|
|
|
Users of a deployed cloud would likely never see this change. It's largely
|
|
targeted at developers of this project or deployers.
|
|
|
|
Deployer impact
|
|
---------------
|
|
|
|
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.
|
|
|
|
Developer impact
|
|
----------------
|
|
|
|
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.
|
|
|
|
Dependencies
|
|
------------
|
|
|
|
This change does not depend on any other blueprints or specs. It can be done
|
|
largely in parallel with other projects and issues.
|
|
|
|
Implementation
|
|
==============
|
|
|
|
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.
|
|
|
|
Assignee(s)
|
|
-----------
|
|
|
|
Other contributors are welcome to work on the mentioned sections.
|
|
|
|
|
|
Primary assignee:
|
|
nolan-brubaker **palendae**
|
|
Other contributors:
|
|
<launchpad-id or None>
|
|
|
|
Work items
|
|
----------
|
|
|
|
* Add the docs directory and some basic structure files, like an index page
|
|
and a Sphinx configuration file.
|
|
|
|
* Add a file for each section to the docs directory, as well as to the index
|
|
page.
|
|
|
|
* Add a Sphinx build job to the gating scripts that only runs if there was a
|
|
change to the docs directory.
|
|
|
|
|
|
Testing
|
|
=======
|
|
|
|
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.
|
|
|
|
|
|
Documentation impact
|
|
====================
|
|
|
|
As mentioned above, this will create a new docs repo that the docs team
|
|
can then build more detailed documentation in reference to.
|
|
|
|
|
|
References
|
|
==========
|
|
N/A
|