documentation as code

什么是 documentation as code 方法

这种方法背后的理念是将文档视为软件源代码的固有部分，因此应使用与开发人员在日常编码相关活动中使用的相同工具和流程来编写和更新文档。

程序员的日常工具包括：

• 问题跟踪器
• 版本控制 (Git)
• 编码 IDE（VS Code、Eclipse、Vim……）
• 纯文本标记语言（Markdown、reStructuredText、Asciidoc）
• 代码审查
• CI/CD

documentation as code 是如何工作的

使用纯文本来写文档

Documentation as Code 背后最重要的思想是文档是用纯文本编写的，纯文本格式的一个优点是它们与开发人员使用的所有 IDE 兼容，因此开发人员可以直接从他们喜欢的 IDE 读取和编辑此类文档与编码方式相同。

这种文件的另一个重要优点是它可以帮助开发人员只关注技术内容，这意味着负责编写文档的团队不必担心它的布局。

由于文档旨在供人类阅读，因此建议采用允许使用基本格式的纯文本格式。技术论文所需的主要格式功能包括：

• 文本突出显示（粗体、斜体和下划线）
• 超文本链接
• 项目符号和编号列表
• 代码块和片段
• 表
• 标题

利用这些简单的特性，内容的可读性将得到显着提升，同时书写体验也不会过重。

文档版本的控制和管理

如果文档是用纯文本编写的，那么开发人员可以很容易地使用相同的版本控制系统（VCS）来管理文档，这与编码的方式相同，因为我们所有的代码都是用纯文本格式编写的。

使用此类 VCS 工具，开发人员可以轻松跟踪所有文档更改，了解这些更改由谁创建以及何时以他们熟悉的方式进行。

由于它的相对易用性和开源的特性，Git 获得了巨大的财富和广泛的传播。事实上，全球最知名和使用最多的平台，即 GitHub 和 GitLab，都是基于 Git 的。

这些工具提供的一大优势是可以与多个人异步处理同一个文件。感谢分支，任何人都可以在他们的设备上创建文件的一个版本，进行更改，然后创建一个拉/合并请求来实施更改。所有这些都不会直接影响原始文件或正在处理同一文件的其他版本的其他人。这些平台还提供了一个界面来轻松报告和解决冲突（即对文件的同一部分进行两个不同的竞争性编辑）。

可以按照你想要的格式发布文档

文档编写、版本控制和保存后，就可以发布了。然后你会问什么是对用户好的格式？在这里，您可能一定认为将具有基本格式的纯文本文档直接发布给用户不是一个好主意。

是的，确实不是一个好主意，但是我们有工具，使用静态站点生成器 (SSG) 可以轻松地将纯文本文件转换为 HTML，允许您添加 CSS 样式表以增强和品牌外观和感觉，如果需要, 还允许您添加动态 JavaScript 部分：然后所有内容都将在服务器端呈现，为客户端提供加载速度非常快的静态页面。

多亏了 SSG，您可以轻松地将内容与其最终的图形表示解耦：开发团队将只负责技术内容，而视觉方面的责任可能会交给另一个团队。这样，开发人员不必担心选择正确的字体、格式化内容或任何其他此类活动：他们只关心将基本格式直接添加到纯文本文件中。此外，通过这种方式，任何图形更改都可以级联到所有页面，只需编辑一个样式表。

大多数 SSG 还提供了一些附加功能，这些功能极大地增强了内容的可用性，但不一定需要开发团队的手动干预。这些附加功能的示例包括：

• 带有子部分链接的主页；
• 侧边栏导航菜单；
• 搜索引擎;
• 锚链接到标题；
• 每页的目录；
• 发行说明管理；
• 管理不同语言的内容；
• 显示以前软件版本的文档。

这些功能本身就非常简单，但它们一起使查找和消费内容变得容易，帮助用户快速找到他们正在寻找的内容。
您甚至可以使用其他工具将纯文本文件转换为其他格式，如 pdf、word 等。

自动化及CI/CD

文档即代码方法的另一个好处是，您可以以与代码相同的方式利用 CI/CD（持续集成和持续交付）系统的自动化。

关于 CI，您可以创建自动化测试，每次在主分支上发出 Pull/Merge 请求时检查内容：此类测试可以检测技术错误（即无效链接、无效代码片段等）或形式错误（即 、拼写错误、缺少标点符号等）。 如果测试失败，团队会收到错误通知并采取措施解决； 如果测试通过，CD 阶段就可以开始了。

作为如何利用 CD 的示例，您将能够创建自动化检测主分支中的所有更改，并自动发布新内容。 这样，您就不必在发布过程上花费时间，而传统上这需要花费大量时间。

使用 documentation as code 维护和发布软件文档的优点

• 更容易学习纯文本文档

纯文本框架提供了标题、超文本链接、文本突出显示和列表等基本语法。这些语法非常容易使用，同时像 reStructuredText 或 Markdown 这样的纯文本框架为基本语法提供了很好的指导，用户可以轻松学习从例子。

• 开发人员更快速高效地编写文档

使用他们每天用来编写代码的相同工具，开发人员将能够只专注于内容，从而更快地生成内容。

• 更好、更准确的文档

通过在编写阶段更快，开发人员将生成更准确的文档，因为编写阶段将在他们想要记录的功能开发后不久发生。另外，如果软件文档和代码在同一个仓库，那么软件变更和文档变更可以在同一个合并请求中，这样审阅者就更容易发现软件和文档之间的不匹配并及时给出评论。

• 发布文件的格式更灵活

文档即代码方法将内容和图形解耦，开发人员只负责内容的准确性，他们不需要关心最终的文档形式，有很多工具可以用来将纯文本转换为不同的漂亮的脸格式像 SSG 一样，这些工具可以很容易地集成到 CI/CD 系统中，以利用文档发布的自动化。

• 完整的版本控制

使用文档即代码方法，您将能够轻松跟踪对文档的每一次更改，并且在出现错误时您将能够轻松回滚。此外，版本控制还允许您检查文档是否是最新的。

• 更轻松的协作

使用文档即代码方法，这些使用的工具旨在鼓励协作，并且通过对它们非常熟悉，开发人员可以更轻松地进行协作，并且他们将更倾向于提出更改和改进的建议。

documentation as code 的工具链

纯文本文档工具

Markdown

Markdown是一种轻量级标记语言，您可以使用它来给纯文本文档添加格式化元素。由John Gruber于2004年创建，Markdown现在是世界上最流行的标记语言之一。

使用Markdown与使用所见即所得（WYSIWYG）编辑器不同。在像Microsoft Word这样的应用程序中，您点击按钮来格式化单词和短语，更改会立即显示出来。但Markdown不是这样的。当您创建一个Markdown格式的文件时，您需要在文本中添加Markdown语法来指示哪些单词和短语应该呈现不同的样式。

例如，要表示一个标题，您在前面加上一个井号（例如，# 标题一）。或者要使短语加粗，您在前后各加两个星号（例如，这段文字加粗）。如果您习惯于使用所见即所得的应用程序，可能需要一些时间来适应在文本中看到Markdown语法。下面的截图显示了在Visual Studio Code文本编辑器中显示的Markdown文件。

您可以使用文本编辑器应用程序向纯文本文件添加Markdown格式化元素。或者，您可以使用适用于macOS、Windows、Linux、iOS和Android操作系统的众多Markdown应用程序。还有一些专为Markdown编写而设计的基于Web的应用程序。

根据您使用的应用程序，您可能无法实时预览格式化的文档，但这没关系。根据Gruber的说法，Markdown语法设计得易读且不显眼，因此即使未呈现，Markdown文件中的文本也是可读的。

Markdonw tools

• Visual Studio Code
• GitBook
• Gitlab Pages
• GitHub Pages
• Jekyll
• MkDocs
• Docusaurus

Restructure Text

reStructuredText是一种易于阅读、所见即所得的纯文本标记语法和解析系统。它适用于内联程序文档（如Python docstrings）、快速创建简单网页和独立文档。reStructuredText旨在为特定应用领域提供可扩展性。reStructuredText解析器是Docutils的组成部分。reStructuredText是StructuredText和Setext轻量级标记系统的修订和重新解释。

reStructuredText的主要目标是定义和实现一种用于Python docstrings和其他文档领域的标记语法，既易读又简单，同时又足够强大以应对非平凡的使用场景。标记的预期目的是将reStructuredText文档转换为有用的结构化数据格式。

Restructure Text tools

• Sphinx
• Read the Docs
• JEdit
• ReText
• Visual Studio Code

MarkDown vs Restructure Text

Diagram as code

图表即代码（Diagram as code）是指使用代码或声明性配置文件来创建图表，而不是传统的图形工具。它涉及使用编程语言或特定的语法来定义图表的结构和元素。

在图表即代码中，您编写描述图表组件、关系和布局的代码。然后，该代码会被工具或框架处理，根据提供的指令生成图表的可视化表示。

使用图表即代码的优点包括：

• 版本控制和协作：由于图表被表示为代码，可以将其存储在像 Git 这样的版本控制系统中，从而允许多个团队成员协作、跟踪更改和管理修订。

• 自动化和一致性：可以根据底层代码或配置文件的更改自动生成或更新图表。这确保图表始终是最新的，消除了手动错误或不一致性的风险。

• 可重用性：以代码方式创建的图表可以在不同项目或环境中轻松重用。可以创建图表组件的模板或库，从而在创建类似图表时更容易维护一致性并节省时间。

• 可扩展性：由于图表被表示为代码，可以以编程方式生成它们，从而更有效地处理大型或复杂的图表。可以利用循环、条件语句和其他编程结构来动态生成图表。

• 集成：以代码方式创建的图表可以集成到持续集成/持续交付（CI/CD）流水线或其他自动化工作流中。这使得图表能够与相关的基础设施或应用代码一起自动生成和部署。

PlantUML

PlantUML是一个基于文本的开源工具，用于创建各种类型的图表，例如UML图、流程图、时序图、类图、用例图等。它使用简单的文本语言来描述图表的元素和关系，然后通过渲染引擎生成相应的图表图像。

使用PlantUML，您可以使用简洁的语法描述图表的结构和特征。例如，您可以使用PlantUML创建一个简单的类图如下：

@startuml
class Car {
  + String make
  + String model
  + void start()
  + void accelerate()
  + void brake()
}

class Engine {
  + void start()
  + void stop()
}

Car --> Engine
@enduml

上述代码使用PlantUML的语法描述了一个Car类和一个Engine类之间的关系，通过箭头表示Car类依赖于Engine类。生成的图表将显示两个类及其之间的关系。

PlantUML提供了丰富的语法和标记，使您能够创建复杂的图表。它支持各种图表类型和元素，允许您通过简单的文本描述快速生成专业的图表。您可以将PlantUML集成到文档、代码注释或其他工作流程中，从而方便地创建和维护图表，并保持其与代码同步更新。

此外，PlantUML还支持与其他工具和平台的集成，如IDE编辑器、文档生成器（如Markdown、HTML）、版本控制系统等。它的开放性和可扩展性使其成为软件开发、系统设计和文档编写的有用工具。

Mermaid

Mermaid和PlantUML非常相似，是一个基于JavaScript的绘图和图表工具，它使用受Markdown启发的文本定义和渲染器来创建和修改复杂的图表。Mermaid的主要目的是帮助文档与开发保持同步。

Graphviz

Graphviz是一个开源的图形可视化工具，它使用简单的文本语言来描述图表的结构和特征。它提供了一组命令行工具，可以将文本文件转换为图表图像。Graphviz支持各种图表类型，包括流程图、组织结构图、时序图、类图、用例图等。

API 文档

Doxygen

Doxygen是生成从注释的C++源代码中生成文档的事实上的标准工具，但它也支持其他流行的编程语言，如C、Objective-C、C#、PHP、Java、Python、IDL（Corba、Microsoft和UNO/OpenOffice版本）、Fortran和在一定程度上的D。Doxygen还支持硬件描述语言VHDL。

Doxygen可以通过以下三种方式帮助您：

• 它可以从一组有注释的源文件中生成在线文档浏览器（HTML）和/或离线参考手册。还支持生成RTF（MS-Word）、PostScript、超链接PDF、压缩HTML和Unix man页的输出。文档直接从源代码中提取，这使得与源代码保持一致的文档更容易。

• 您可以配置Doxygen从未有注释的源文件中提取代码结构。这对于在大型源代码分发中快速定位非常有用。Doxygen还可以通过包括依赖关系图、继承图和协作图来可视化各个元素之间的关系，这些图都是自动生成的。

• 您还可以使用Doxygen创建常规文档（就像我为Doxygen用户手册和网站所做的那样）。
  Doxygen在Mac OS X和Linux下开发，但也具有高度可移植性。因此，它也可以在大多数其他Unix版本上运行。此外，还提供了Windows的可执行文件。