项目指南设置¶
OpenStack 项目应遵循本章中的指南来设置其文档结构，以便于查找其文档并在 OpenStack 项目之间保持一致性。
为了便于从 docs.openstack.org 上的登陆页面包含链接，我们需要确保文档目录的组织结构达到最低限度的一致性。这些章节基于过去几年发展起来的高级分组。
在每个顶级目录下，项目团队可以自由地组织内容，只要他们认为最合适即可。
这是 Pike 及以后版本中实施的布局
doc/source/install/– 与项目安装相关的任何内容。contributor/– 与为项目贡献或团队管理相关的内容。这适用于之前/developer下的一些内容，名称更改是为了强调并非所有贡献者都是开发者，有时开发者是用户但不是贡献者。服务项目应将自动生成的类文档放置在此树的这部分，例如在contributor/api或contributor/internals中。configuration/– 基于 oslo.config 的 sphinx 集成（或对于未使用 oslo.config 的项目手动编写）自动生成的配置参考信息。启用 cells 或配置特定驱动程序等逐步指南应放置在admin/部分中。cli/– 命令行工具参考文档，类似于 man 页面。这些可以使用 cliff 的 sphinx 集成自动生成，或者在无法自动生成时手动编写。使用这些工具的教程或其他逐步指南应放在user/或admin/部分中，具体取决于其受众。由于每个项目的文档应与代码一起存储在仓库中，因此此目录可能并非所有服务仓库都存在，但对于大多数客户端库仓库而言，它都将存在。admin/– 来自旧管理指南的任何内容或讨论如何运行或操作软件的任何内容。这包括从一个版本更新到较新版本。user/– 最终用户内容，例如概念指南、建议、教程、使用 CLI 执行特定任务的逐步说明等。reference/– 与项目关联的任何参考信息，不包含在上述类别中。库项目应将自动生成的类文档放置在此处。
此布局是最低集合。项目可以自由地并鼓励添加超出此列表的任何其他文档，但此处明确列出这些项目是因为已经存在从登陆页面到大多数项目的链接，并且可以为其他项目创建登陆页面。
在后续阶段，我们将把 API 参考和发布说明构建合并到同一个作业中，以及项目的其余文档。然而，这两个构建都有自定义的考虑因素，并且移动不再由文档团队维护的内容更为重要。
doc/source/api/– REST API 参考和指南内容（如果存在）。releasenotes/– reno 指令（实际的发布说明输入将保留在 /releasenotes/notes 中，就像现在一样）。
注意
对 api/ 和 releasenotes/ 目录布局的进一步讨论将推迟到我们完成初始迁移工作之后。如果您创建内容，请随时按照上述规范使用这些目录。
