Project guide setup

OpenStack projects should follow the guidelines in this chapter for
setting up their documentation structure to make it easy to find their
documents and have consistency between OpenStack projects.

To make it easy to include links from the landing pages on
docs.openstack.org, we need to ensure a minimum level of consistency
in the organization of the docs directory. The sections are based on
high-level groupings that have evolved over the last years.

Within each top-level directory, project teams are free to organize
their content however seems most appropriate to them.

This is the layout implemented in Pike and later:

doc/source/

install/ – anything having to do with installation of the
project.

contributor/ – anything related to contributing to the
project or how the team is managed. This applies to some of the previous
content under /developer, the name is changed to emphasize
that not all contributors are developers and sometimes developers
are users but not contributors. Service projects should place
their automatically generated class documentation under this part
of the tree, for example in contributor/api or
contributor/internals.

configuration/ – automatically generated configuration
reference information based on oslo.config’s sphinx integration
(or manually written for projects not using
oslo.config). Step-by-step guides for doing things like enabling
cells or configuring a specific driver should be placed in the
admin/ section.

cli/ – command line tool reference docs, similar to man pages.
These may be automatically generated with cliff’s sphinx
integration, or manually written when auto-generation is not
possible. Tutorials or other step-by-step guides using these
tools should go in either the user/ or admin/ sections,
depending on their audience. Because the documentation for each
project should live in the repository with the code, this
directory may not be present for all service repositories but will
be present for most of the client library repositories.

admin/ – any content from the old admin guide or anything
else that discusses how to run or operate the software. This
includes updating from one release to a newer version.

reference/ – any reference information associated with a
project that is not covered by one of the above categories.
Library projects should place their automatically generated class
documentation here.

This layout is the minimum set. Projects are free and encouraged to
add whatever other docs they need beyond this list, but these items
are listed here explicitly because there are already links to most of
them from landing pages, and landing pages can be created for the
others.

During a later phase, we will merge the API reference and release notes builds
into the same job, along with the rest of the documentation for a project.
Both of those builds have custom considerations, though, and it is more
important to move the content that is no longer going to be maintained
by the documentation team.

doc/source/

api/ – the REST API reference and guide content, when it exists.

releasenotes/ – reno directions (the actual release notes
inputs will stay in /releasenotes/notes, where they are now).

Note

Further discussion of the layout of the api/ and
releasenotes/ directories is deferred until we are further
along with the initial migration work. If you create content, feel
free to use these directories already as specified above.