文档¶

本节包含为 OpenStack 文档做出贡献所需的信息。

项目仓库中的文档¶

所有项目文档必须遵循相同的目录结构，该结构在项目指南设置页面上描述。

文档目录结构如下

└── source
    ├── admin
    ├── cli
    ├── configuration
    ├── contributor
    ├── install
    ├── reference
    └── user

安装指南可以在 install 目录中找到。它包含有关从软件包安装项目的所有信息，例如，安装项目所需的软件，如数据库安装和配置，或者项目中 config 文件应设置哪些参数。如果一切配置正确（如下所述），项目的安装指南将包含在 OpenStack 安装指南中。安装指南不适用于生产系统安装。

贡献者指南可以在 contributor 目录中找到。它包含有关为项目做出贡献和团队管理的特定项目信息。本指南仅出现在项目的文档中。

configuration 目录包含配置参考信息，这些信息是自动生成的（如果项目使用 oslo.config）或手动编写的（如果未使用 oslo.config）。有关更多信息，请参阅 Sphinx 集成。

cli 目录包含命令行工具参考文档，可以使用 cliff 的 sphinx 集成自动生成，或者在无法自动生成时手动编写。有关更多信息，请参阅 cliff Sphinx 集成。

管理员指南可以在 admin 目录中找到。它包含有关软件配置和操作的信息。项目的管理员指南包含在 OpenStack 管理员指南中。

user 目录包含面向最终用户的信息，例如，概念指南、教程、使用 CLI 或项目 API 的分步说明等。

reference 目录包含不包含在其他目录中的参考信息，例如，库项目中的自动生成的类文档。

为了使项目文档链接到 OpenStack 文档门户上，必须更新 openstack-manuals 仓库中的 www/project-data/latest.yaml 文件，并遵循模板生成器的规则。

将所有适用的文档选项设置为“true”。例如

has_install_guide: true
has_api_ref: true
has_admin_guide: true
has_config_ref: true
has_user_guide: true

如果项目仓库中存在上述结构并且更新了 latest.yaml 文件，则 project-config 仓库中的 publish-openstack-sphinx-docs 作业将自动将文档包含在已发布的文档中。有关详细说明，请参阅项目指南设置。