![Brian Rosmaita](/assets/img/avatar_default.png)
Update some of the information for documentation contributors and correct some formatting. Change-Id: Ib22c8ca5b5ea98a95ee435c242435310fe3dcb0c
6.0 KiB
Contributing Documentation to Cinder
Starting with the Pike release, Cinder's documentation has been moved
from the openstack-manuals repository to the docs
directory
in the Cinder repository. This makes it even more important that Cinder
add and maintain good documentation.
Note
Documentation for python-cinderclient and os-brick has undergone the same transition. The information here can be applied for those projects as well.
This page provides guidance on how to provide documentation for those who may not have previously been active writing documentation for OpenStack.
Documentation Content
To keep the documentation consistent across projects, and to maintain quality, please follow the OpenStack Writing style guide.
Using RST
OpenStack documentation uses reStructuredText to write documentation.
The files end with a .rst
extension. The .rst
files are then processed by Sphinx to build HTML based on the RST
files.
Note
Files that are to be included using the .. include::
directive in an RST file should use the .inc
extension. If
you instead use the .rst
this will result in the RST file
being processed twice during the build and cause Sphinx to generate a
warning during the build.
reStructuredText is a powerful language for generating web pages. The documentation team has put together an RST conventions page with information and links related to RST.
Building Cinder's Documentation
To build documentation the following command should be used:
tox -e docs,pep8
When building documentation it is important to also run pep8 as it is easy to introduce pep8 failures when adding documentation. (The tox pep8 job also runs doc8, but currently we do not run doc8 as part of the tox docs job.)
Note
The tox documentation jobs (docs, releasenotes, api-ref) are set up to treat Sphinx warnings as errors. This is because many Sphinx warnings result in improperly formatted pages being generated, so we prefer to fix those right now, instead of waiting for someone to report a docs bug.
During the documentation build a number of things happen:
- All of the RST files under
doc/source
are processed and built.- The openstackdocs theme is applied to all of the files so that they will look consistent with all the other OpenStack documentation.
- The resulting HTML is put into
doc/build/html
.
- Sample files like cinder.conf.sample are generated and put into
doc/source/_static
. - All of Cinder's
.py
files are processed and the docstrings are used to generate the files underdoc/source/contributor/api
After the build completes the results may be accessed via a web
browser in the doc/build/html
directory structure.
Review and Release Process
Documentation changes go through the same review process as all other changes.
Note
Reviewers can see the resulting web page output by clicking on
openstack-tox-docs
in the "Zuul check" table on the review,
and then look for "Artifacts" > "Docs preview site".
This is also true for the build-openstack-api-ref
and
build-openstack-releasenotes
check jobs.
Once a patch is approved it is immediately released to the
docs.openstack.org website and can be seen under Cinder's Documentation
Page at https://docs.openstack.org/cinder/latest\
. When a new release is cut a snapshot of that documentation will be
kept at https://docs.openstack.org/cinder/<release>
.
Changes from master can be backported to previous branches if
necessary.
Doc Directory Structure
The main location for Cinder's documentation is the
doc/source
directory. The top level index file that is seen
at https://docs.openstack/org/cinder/latest resides here
as well as the conf.py
file which is used to set a number
of parameters for the build of OpenStack's documentation.
Each of the directories under source are for specific kinds of
documentation as is documented in the README
in each
directory:
../admin/README ../cli/README ../configuration/README ../contributor/README ../install/README ../reference/README ../user/README
Finding something to contribute
If you are reading the documentation and notice something incorrect or undocumented, you can directly submit a patch following the advice set out below.
There are also documentation bugs that other people have noticed that you could address:
- https://bugs.launchpad.net/cinder/+bugs?field.tag=doc
- https://bugs.launchpad.net/python-cinderclient/+bugs?field.tag=doc
- https://bugs.launchpad.net/os-brick/+bugs?field.tag=doc
- https://bugs.launchpad.net/cinderlib/+bugs?field.tag=doc
Note
If you don't see a bug listed, you can also try the tag 'docs' or 'documentation'. We tend to use 'doc' as the appropriate tag, but occasionally a bug gets tagged with a variant.