openstack-ansible 概述文档¶

日期:: 2015-04-13 13:00
标签:: 文档, 文档, 开发者

目前，openstack-ansible 仓库没有连贯的开发者文档。本提案旨在开始编写此类文档，为新贡献者提供概述和参考。

本提案涵盖的文档并非旨在详尽无遗。

此外，文档是一个不断变化的事物 - 本提案仅旨在创建初始文档；文档维护不在本次提案的范围内。审查者应帮助确保补丁充分更新相关的文档。

本提案的蓝图可以在这里找到：

https://blueprints.launchpad.net/openstack-ansible/+spec/developer-docs

问题描述¶

目前，当新贡献者来到仓库时，没有太多内容可以帮助他们理解项目的总体结构。目前，有一个 development-stack.rst 文件，它提供了关于启动一体化 (AIO) 安装以及拆除环境的非常简短的介绍，但除此之外没有太多内容。这对于新手以及可能忘记大型代码库某些部分的现有贡献者来说都可能令人望而却步。

提议的变更¶

本提案建议创建一个新的文档仓库，其中包含关于以下文档的 Sphinx 文档：

使用 openstack-ansible 进行部署的概述
变量文件，用于了解在流程的哪个位置使用哪些变量文件。
脚本。本节将涵盖使用 bootstrap、gating 和 teardown 脚本。它还可能记录这些脚本的一些重要变量/参数。openstack-ansible 包装器也应该在这里以及扩展部分进行介绍。
Playbook 应该记录准备物理主机、创建容器和安装 OpenStack 的高级 playbook。
仓库角色/playbook。由于该仓库对于 openstack-ansible 来说非常独特，因此应该比文档的其余部分更详细。openstack_services.yml 和 openstack_other.yml 文件在这里尤其重要。
库存管理。本节应讨论 dynamic_inventory.py 文件和 inventory_management.py 文件。
扩展 openstack-ansible。这将涵盖使用 conf.d 和 env.d 目录以及 user_extras.yml 文件。可能对 ansible.cfg 的必要更改也很有用。

此外，文档目录应定期由 Sphinx 构建，最好在 gating 过程中构建。

有些主题明确不在本次更改的范围内。特别是：

主机网络设置。这高度依赖于每个环境，并且太大，无法在此处涵盖。
单个角色。单个角色不应作为本部分进行记录。角色太多，变化也太多，无法在 openstack-ansible 级别跟上这些变化。
最终用户文档。对于本规范，'最终用户'是部署者或已部署 OpenStack 系统的用户。安装指南、操作指南以及用户/管理员指南均不在本次范围内。

备选方案¶

我们可以不编写此文档，让仓库保持原样。

Playbook 影响¶

本次更改不会对 playbook 产生影响；它只是添加了 playbook 之外的文件。

升级影响¶

此文档必须与发布保持同步。由于文档是一个持续的过程，因此需要审查者强制执行对 playbook 更改的文档更新。

安全影响¶

由于本次更改不是对 playbook 或脚本的更改，因此不应产生任何安全影响。

性能影响¶

这不会对生产性能产生影响。我建议将文档构建作业添加到 gating 过程中，这将延长 gating 作业时间，但具体时间未知。

最终用户影响¶

已部署云的用户可能永远不会看到此更改。它主要面向该项目的开发人员或部署者。

部署者影响¶

部署者影响应该很小或没有。此文档主要面向开发人员，但部署者可以将其用作运行其部署中的脚本和工具的参考。

开发人员影响¶

此文档主要面向开发人员，希望这样可以更容易让新贡献者了解项目的工作方式和从哪里开始。这也可以作为现有开发人员的参考。

Sphinx 构建过程可能会增加一些开销，因为开发人员应该在推送更改之前构建文档。

与 CONTRIBUTING.txt 的不同之处在于重点 - CONTRIBUTING.txt 主要关注将更改纳入代码库的过程。相反，docs 目录应涵盖有关如何使用仓库的技术信息。

依赖项¶

本次更改不依赖于任何其他蓝图或规范。它可以与其他项目和问题并行进行。

实现¶

如前所述，这将使用 ReST 文件在仓库根目录下的 docs 目录中实现。此外，dev-requirements 中将存在对 Sphinx 的依赖，并在 gate 中添加一个脚本来运行 Sphinx 文档构建作业。

负责人¶

其他贡献者可以参与编写上述部分。

主要负责人: nolan-brubaker palendae
其他贡献者: <launchpad-id 或 None>

工作项¶

添加 docs 目录和一些基本结构文件，例如索引页面和 Sphinx 配置文件。
将每个部分的文件添加到 docs 目录以及索引页面。
将 Sphinx 构建作业添加到 gating 脚本中，仅当 docs 目录发生更改时才运行。

测试¶

本次更改将向 gating 过程添加 Sphinx 构建作业。Sphinx 构建作业不应在没有受影响的文档文件的更改上运行。

Sphinx 文档构建作业应成功才能合并更改。

文档影响¶

如上所述，这将创建一个新的文档仓库，文档团队可以在此基础上构建更详细的文档。

参考资料¶

N/A

openstack-ansible 概述文档