[ English | Indonesia | 한국어 (대한민국) | español (México) | English (United Kingdom) | Deutsch | 中文 (简体, 中国) ]
Documentation¶
This section contains information necessary to contributing to OpenStack documentation.
Documents in project repositories¶
All project documentation must follow the same directory structure, which is described on the Project Guide Setup page.
The documentation directory structure is the following:
└── source
├── admin
├── cli
├── configuration
├── contributor
├── install
├── reference
└── user
Installation guide¶
The installation guide can be found in the install
directory. It contains
information on anything to do with installing a project from packages, for
instance, software necessary for installing the project, like database
installation and configuration, or what parameters should be set in the
project’s config file. If everything is configured properly (described below),
the project’s installation guide is included in the OpenStack Installation
Guides. The installation guide is not intended to be used for production
system installations.
Contributor guide¶
The contributor guide can be found in the contributor
directory. It
contains project-specific information on contributing to the project and on
team management. This guide appears only in the project’s documentation.
Configuration reference¶
The configuration
directory contains configuration reference information
that is either automatically generated (if the project uses oslo.config
) or
manually written (if oslo.config
is not used). For more information, see
Sphinx Integration.
CLI reference¶
The cli
directory contains command line tool reference documentation which
can be automatically generated with cliff’s sphinx integration, or manually
written when auto-generation is not possible. For more information, see
cliff Sphinx Integration.
Administrator guide¶
The admin guide can be found in the admin
directory. It contains
information on the configuration and operation of the software. The project’s
administrator guide is included in the OpenStack Administrator Guides.
User guide¶
The user
directory contains information targeted at end-users, for
instance, concept guides, tutorials, step-by-step instructions for using the
CLI or the project’s API, and such.
Reference documents¶
The reference
directory contains reference information not included in the
other directories, for instance, automatically generated class documentation in
library projects.
Publishing documents in project repositories¶
For the project documents to be linked to on the OpenStack documentation
portal, the www/project-data/latest.yaml
file in the
openstack-manuals
repository has to be updated, following the rules of the
template generator.
Find your project in the file.
Set to ‘true’ all document options that apply. For example:
has_install_guide: true has_api_ref: true has_admin_guide: true has_config_ref: true has_user_guide: true
If the above structure exists in the project repository and the latest.yaml
file is updated, the publish-openstack-sphinx-docs
job in the
project-config
repo automatically includes the document in the published
documentation. For detailed instructions, see the Project guide setup.