重构 CloudKitty 的文档

https://storyboard.openstack.org/#!/story/2004179

CloudKitty 的文档需要重构。本规范旨在提出新的内容布局。当然，这需要讨论，既在 storyboard 上，也在 gerrit 上。

问题描述

由于 Cloudkitty 在最近几个版本中经历了重大变化，当前文档的布局和内容导致了一些问题

  • 布局不够直观：许多人在 IRC 上询问文档中已有的信息，但很难找到。

  • CloudKitty 的架构以及每个组件（fetcher、collector、rating module、存储后端…）的作用没有解释清楚。这对操作员来说是一个问题，因为他们不了解 CloudKitty 的内部工作原理，这在故障排除时是一个问题。

  • 指标收集的配置文档非常糟糕，导致大多数操作员坚持使用默认的 metrics.yml 文件，而不知道每个条目的确切含义。

  • 开发者文档几乎不存在：它仅包含有关 v2 存储接口的信息。应该扩展它以帮助贡献者。

  • 文档也缺少 FAQ/故障排除部分：一个典型的问题是“我使用 Devstack 部署了 Cloudkitty，为什么 summary 为 0？”。

提议的变更

文档的第一件事应该是 CloudKitty 是什么以及它做什么的简要介绍。关于阅读 CloudKitty 文档的人：他们可以分为三类；用户、操作员/管理员和开发者。因此，在简短的介绍之后，建议的顶级部分如下

  • 通用介绍：Cloudkitty 旨在解决什么问题/需求？什么可行？什么（目前）不可行？什么将永远不受支持？

    除了这些问题，还应该对不同的组件、它们的作用以及它们如何交互进行一般介绍。

  • 用户文档：如何通过 cloudkitty 的 API 检索信息？可以获得哪些信息？

  • HTTP API 参考。但是，v2 API 的参考将在其被认为稳定后发布到 developer.openstack.org/api-ref。

  • 操作员文档：本节应详细说明每个组件的作用，并提供有关如何配置它的信息。评级规则的创建信息也应在此处提供。操作员也是故障排除部分的受众。

    与当前方法（使用 keystone/openstack 与不使用 keystone/openstack）相反，我认为文档的这部分应该逐个解释每个组件：它的用途、如何使用它、现有的实现（列出不同的 collectors/fetchers/rating modules，并理想地提供支持矩阵）以及如何配置它。

    一个配置难以从文档中推断的用例示例：CloudKitty 在没有 keystone 身份验证的情况下使用，并收集 prometheus 指标。但是，为了从 gnocchi 收集指标，collector 需要向 keystone 身份验证。如何配置？

  • 开发者文档：本节应提供有关 cloudkitty 组成的各个组件的实现细节。它应该解释贡献者需要实现什么、他们应该使用哪些接口以及他们的贡献应该如何测试。理想情况下，这应该完善接口的文档字符串。可以在这里找到这样一个文档的示例（可能不够完整）：https://docs.openstack.org/cloudkitty/latest/developer/storage.html

    再次，文档应按组件划分。

备选方案

我没有想到任何替代的布局或内容，但欢迎提出建议！

数据模型影响

无

REST API 影响

没有，除了可能对 API 进行更好的文档记录。

安全影响

无

通知影响

无

其他最终用户影响

最终用户和贡献者将更好地理解该项目。

性能影响

无

其他部署者影响

更好地理解该项目，故障排除更容易。

开发人员影响

更好地理解该项目，贡献更容易。

实现

负责人

Luka Peschke 被分配了规范的工作以及将新的布局集成到文档中。在规范审查、更正和合并后，文档内容的工作将被分配。

主要负责人

peschk_l

其他贡献者

无

工作项

  • 将新的布局应用于 cloudkitty 的文档

  • 编写带有几个模式的介绍

  • 通过一个提交/任务对，逐步改进文档的（子）部分，每个主题对应一个。

依赖项

无

测试

无

文档影响

文档将被完全修改，并且将添加大量内容。

参考资料