在 AWS 上部署文档即代码：在 MkDocs 和 Docusaurus 中构建动态文档站点

在本文中，我将指导您一步一步创建一个适用于任何项目的动态文档站点，您可以在其中将文档连接到数据库以提取和显示数据，确保信息始终是最新的。我们还将探索如何使用 AWS.

自动化整个流程，从内容生成到云中部署

该解决方案包括对图表和图表的支持、使用 GitHub Actions 中简单工作流程的持续集成 (CI/CD) 以及使用 Terraform 的自动部署。让我们开始吧！

---

什么是文档即代码？

文档及其更新是许多开发软件的公司的重要流程，通常使用不同的工具进行，其中许多是付费解决方案。

因此，最近出现了“doc as code”的概念。这意味着使用软件开发中使用的相同工具和工作流程来管理、版本和部署文档。

这种方法不仅可以更好地跟踪文档，还可以促进其维护，并确保与软件开发中使用的相同最佳实践保持一致，不仅在代码中，而且在文档中。

---

将文档作为代码的工具

对于这些网站的开发，有必要了解一些允许我们实施这种方法的实践和工具。以下是本教程中要涵盖的最重要方面的详细列表。

• ？ Markdown：由于其简单性以及与版本控制平台和静态站点生成器的集成，是编写文档最常用的标记语言。
• ?️ Git：Git 允许像代码一样对文档进行版本控制。感谢 Git，记录了文档中的每一个更改，使团队能够跟踪编辑、恢复更改并更有效地协作。
• ？ Gitflow：此方法提供了一个结构化的工作流程来管理文档的版本和修订，确保更改在投入生产之前得到批准和测试。 Gitflow 还促进团队之间的协作，从而实现安全且有组织的变更管理。
• ☁️ 云服务：使用 AWS S3、Netlify 或 GitHub Pages 等服务，您可以以较低的成本部署文档。这些服务允许创建快速、安全且易于访问的静态站点。
• ？ 静态站点生成器：Docusaurus、Jekyll 或 Hugo 等工具将 Markdown 文档转换为可导航的网站，使您无需服务器即可创建丰富且有组织的文档。
• ？ 持续集成 (CI/CD)：CI/CD 管道（例如 GitHub Actions、GitLab CI 或 Jenkins）允许您在合并新版本或批准修改时自动部署文档。这可确保文档始终是最新的。

---

文档即代码的优点

• ✅ 一致性和质量：通过使用版本控制和变更审核，文档保持一致且高质量。
• ⚙️ 自动化：CI/CD 工具可实现文档部署的自动化，减少更新时间并最大限度地减少错误。
• ？高效协作：借助 Git 等工具，团队可以协作创建和维护文档，而不会发生冲突。
• ？简化维护：维护文档已集成到开发工作流程中，随着代码的发展，更新变得更加容易。

---

？ MK文档

MkDocs 是一个用 ?Python 编写的静态站点生成器，专为文档项目而设计。其目标是简化使用 Markdown 文件创建文档，这些文件易于编写和阅读。

通过最少的配置，MkDocs 将 Markdown 文件转换为可导航且结构良好的文档网站，使其成为想要保持文档最新的开发人员和团队的理想选择。

---

✏️ MkDocs 材料

MkDocs Material 是 MkDocs 的高级主题，遵循 Google 的 Material Design 指南。

？主要特点包括：

• ？ 响应式设计：自动适应任何屏幕尺寸。
• ？ 自定义：轻松修改颜色、字体、图标和徽标以匹配您项目的视觉识别。
• ？ 搜索界面：高级搜索对结果进行分组并突出显示搜索的术语，帮助用户找到所需的信息。
• ⚡ 延迟加载：对搜索结果实现延迟加载，提高性能并减少加载时间。
• ？ 集成：兼容Google Analytics、Disqus和GitHub，方便流量分析、用户反馈以及直接连接到项目存储库。

---

✏️美人鱼

Mermaid 是一个 JavaScript 库，用于从文本创建图表。通过与 MkDocs Material 集成，Mermaid 允许您在文档中生成可视化效果，例如流程图、实体关系图和文档中的其他图表，而无需外部工具。

---

？动态页面：Jinja

Jinja 是一个库，允许将 Python 字典中的变量和数据嵌入到 HTML 中，使网页动态化。该库通常用于生成动态 HTML 和发送个性化电子邮件。

---

？多库龙概述

Docusaurus 是 Meta 于 2007 年开发的一个开源项目，它以快速高效的方式简化了文档网站的创建、部署和维护。它允许使用 Markdown 和 MDX 来编写内容，而其基于 React 的核心可以完全自定义样式，以满足项目的特定需求。

此外，Docusaurus 通过 @docusaurus/theme-mermaid 插件支持 Mermaid，从而可以直接在文档中包含图表和图表。

---

？图表即代码

图表即代码是一种允许您通过代码而不是使用传统图形工具来创建图表的方法。您无需手动构建图表，而是在文本文件中编写代码来定义图表的结构、组件和连接。

然后该代码被转换为图形图像，从而更容易在软件项目中集成和记录。它对于以编程方式创建和更新架构图和流程图特别有用。

？图表即代码：创建云图的示例

如前所述，图表允许您使用主要云技术的图标生成蓝图。这些图表的表示是通过节点完成的，在我们的示例中，我们将使用所有与云相关的节点和 AWS 服务。

有关我如何创建它的更多详细信息，您可以阅读我关于图表即代码的文章，完整的实现可以在此存储库中找到：

罗米门德斯 / 图表即代码

有关如何使用“文档为图表”方法创建文档项目的教程

---

？图表即代码：为视觉内容创建动态和交互式文档

图表即代码是一种允许您通过代码而不是传统图形工具创建图表的方法。您可以在文本文件中编写代码来定义图表的结构、组件和连接，而不是手动构建图表。

然后，该代码被转换为图形图像，从而更容易在软件项目中集成和记录，这对于以编程方式创建和更新架构和流程图特别有用。

什么是图表？

Diagrams 是一个 ?Python 库，它实现了图表即代码方法，使您能够通过代码创建架构基础设施图和其他类型的图表。借助图表，您只需几行代码即可轻松定义云基础设施组件（例如 AWS、Azure 和 GCP）、网络元素、软件服务等。

？图即代码的好处

• ？…

在 GitHub 上查看

---

？用例：为机器学习项目创建文档站点

在此用例中，我将为 机器学习项目 创建一个文档网站，涉及 ?医院数据。目标是最初使用 MkDocs 构建一个交互式文档站点，然后将其迁移到 Docusaurus。该网站将包括静态和动态组件以满足特定要求，例如嵌入可视化图表和从 SQLite 数据库动态更新数据。

---

？文档站点的主要功能

1. 视觉表示：我将嵌入使用图表（图表即代码）创建的图表来有效地说明机器学习管道的架构。
2. 动态数据更新：文档将动态显示版本和上次更新日期，从SQLite 数据库提取此信息以确保准确性和相关性。
3. 数据示例：文档将包含 Synthea 患者表中的示例，以展示合成数据作为示例。

---

？网站页面

因此，我们的文档网站将包含以下页面：

• ？ Home：文档的主页。
• ？表格：Synthea 数据表及其用途的说明。
• ？架构：托管在 AWS 上的数据处理架构的详细概述。
• ？词汇表：整个项目中使用的术语表

---

MkDocs 实施

在本节中，我们将逐步完成使用 MkDocs 从头开始​​设置文档项目的步骤，并解释其组织的目录结构。

？ MkDocs 的先决条件

首先，您需要安装以下 ?Python 库：

安装 MkDocs 和材质

  pip install mkdocs mkdocs-material

安装额外的库以启用动态内容更新

  pip install aiosql pandas sqlite3 jinja2 shutil

---

？ Mkdocs：项目设置

初始化项目

首先创建一个新的 MkDocs 项目。在终端中运行以下命令：

   mkdocs new mkdocs
   cd mkdocs

此命令创建一个具有默认结构的基本 MkDocs 项目。

探索目录结构

创建 MkDocs 站点后，您需要添加以下文件和文件夹，因为默认情况下不包含它们。 
请记住，本文末尾提供了存储库的链接供您参考，下面将详细解释每个组件。

  pip install mkdocs mkdocs-material

---

?Mkdocs：组件概述

Component	Directory	Description
Database (db)	db	Contains the SQLite database (hospital.db) and queries (metadata.sql, person.sql) to manage dynamic data. Learn more about managing SQL queries in Python in my previous article: Python Projects with SQL.
?️ Templates & Pages	template	Markdown templates: index.md, tables.md, architecture.md, glossary.md. Supports Mermaid diagrams, embedded images, and database-driven content.
?️ Static Content (docs)	docs	Final site generated by update.py, including images (img/) and dynamic content populated from template.
? Infrastructure (infraestructure)	infraestructure	Terraform scripts (main.tf, variables.tf) to deploy an S3 bucket for documentation hosting.

---

？ Mkdocs：配置 mkdocs.yml

一旦我们设置了项目结构，我们将从 mkdocs.yml 文件开始逐步配置它。该文件定义文档站点的结构和设置。它的结构如下：

mkdocs.yml

  pip install mkdocs mkdocs-material

在此配置文件中，您主要可以在nav部分中看到可从菜单访问的页面。然后，我们指定 Mermaid 扩展，这将在下一节中解释。最后，主题部分应用Material主题，启用该库中可用的样式和组件。

---

✏️ Mkdocs：美人鱼扩展

如前所述，Mermaid 是一个 JavaScript 库，用于从文本创建图表和图表。下面，我们将看到一些例子。在我们的例子中，我们将使用它在文档的表页面上生成实体关系图（ERD）。

在存储库中，您将能够了解如何根据 Synthea 官方文档中的实体关系图 (ERD) 构建此代码。您还可以在以下链接中查看表格页面的示例：tables.md.

---

⚙️ Mkdocs：使用 Jinja 的动态内容

为了为我们的文档站点启用动态内容生成，我们将使用 Jinja 来处理模板并用实际数据替换占位符。以下是逐步细分：

1. 设置模板文件夹
   
   创建一个名为 templates 的文件夹来存储站点的所有 Markdown 文件。这些文件应包含占位符。例如，在index.md中，您可能有像{{database.version_date}}和{{database.version}}这样的占位符。

2. 使用占位符
   
   占位符是 Markdown 文件中的动态变量。这些变量将使用Python字典自动更新以注入相关数据。

3. 使用 update.py 生成动态内容

   • 通过识别需要动态数据的部分来准备 Markdown 模板。
   • 使用我的存储库中提供的 Python 脚本 (update.py) 来处理模板。该脚本执行以下任务：
     • 数据库连接：连接到 SQLite 数据库以获取最新值。
     • 模板渲染：使用 Jinja 库用数据库中的数据替换占位符。
     • 文件生成：将更新的 Markdown 文件输出到 docs 文件夹，准备在 MkDocs 中渲染。

  pip install mkdocs mkdocs-material

  pip install aiosql pandas sqlite3 jinja2 shutil

通过执行这些步骤，您可以自动执行文档站点的更新过程，确保内容保持动态和相关性，而无需手动编辑。

---

数据表动态更新

在下一个示例中，我们将更新tables.md 文件中的内容以显示数据库中的persons 表的示例。为此，我们将在 Markdown 文件中创建一个占位符 {{table.person}}。这个想法是动态地从 persons 表中获取数据，然后使用 Jinja 库和 pandas 将查询结果转换为 Markdown 表格式。

以下是使用占位符时tables.md 文件的外观示例：

   mkdocs new mkdocs
   cd mkdocs

流程如下：

1. 查询数据库：脚本将查询SQLite数据库中的persons表以获取相关记录。
2. 转换为 Markdown：使用 pandas，将查询结果转换为 Markdown 表格格式
3. 替换占位符：tables.md 文件中的 {{table.person}} 占位符将被生成的 Markdown 表格替换。

   ? docs/
     ├── ? img/
     ├── `architecture.md`
     ├── `glossary.md`
     ├── `index.md`
     ├── `tables.md`
     ├── ? template/
     │   ├── ? db/
     │   │   ├── ? data/
     │   │   │   ├── hospital.db
     │   │   ├── ? queries/
     │   ├── `architecture.md`
     │   ├── `glossary.md`
     │   ├── `index.md`
     │   ├── `tables.md`
     │   └── `update.py`
   ? infraestructure/
   ? github/
     ├── ? workflows/
     │   ├── main.yml
   ? mkdocs.yml

这样，文档始终反映最新数据，根据数据库中的实际内容显示动态示例。

---

⚙️ Mkdocs：最终工作流程

1. 创建模板：在 docs/template 目录中开发页面。
2. 运行 update.py：填充动态内容并在 docs/output 中生成最终文件。
3. 本地预览：使用 mkdocsserve 在本地主机上预览站点。
4. 构建部署：使用 mkdocs build 在 docs/ 文件夹中生成静态站点。
5. 部署：使用 Terraform 将站点部署到 AWS S3 存储桶。有关详细说明，请参阅本文的部署部分。

---

？ Docusaurus 实施

在以下部分中，我将提供有关如何使用 Docusaurus 实现文档站点的详细步骤和见解。这包括设置、自定义和部署选项。

---

？ Docusaurus 的主要特点

• ？ Mermaid 支持：与 MkDocs 类似，Docusaurus 支持 Mermaid 嵌入图表。
• ⚛️ React 组件：Docusaurus 基于 React 构建，可以将动态组件集成到文档中。
• ？ 动态内容：利用 Python 脚本从 SQLite 数据库动态获取和更新内容。

---

？ Docusaurus 设置：从头开始

要开始使用 Docusaurus，我们遵循快速设置过程，该过程与我们用于 MkDocs 的步骤非常相似，但使用不同的工具。

1. 创建一个新的 Docusaurus 项目： 首先，安装 Node.js 并运行以下命令来创建新的 Docusaurus 站点：

  pip install mkdocs mkdocs-material

1. 安装美人鱼包： 要启用美人鱼图，请安装所需的软件包：

  pip install aiosql pandas sqlite3 jinja2 shutil

1. 运行开发服务器： 安装后，导航到您的项目目录并运行开发服务器：

   mkdocs new mkdocs
   cd mkdocs

1. 访问网站： 您的网站将在本地运行：http://localhost:3000。

---

？ Docusaurus 定制：配置

配置文件 docusaurus.config.js 是我们自定义标题、主题、导航以及启用 Mermaid 等功能以进行图表渲染的地方。
启用美人鱼的示例片段：

  pip install mkdocs mkdocs-material

---

？ Docusaurus 自定义主页

为了自定义主页，我们修改 src/components/HomepageFeatures/index.js 文件。在这里，您可以调整 FeatureList 对象来更新主页上显示的功能。

---

？ Docusaurus 内容组织和结构

就像在 MkDocs 中一样，Docusaurus 支持 Markdown 文件 作为内容，我们按如下方式组织结构：

1. 模板文件夹：将 Markdown 文件存储在 docs/template 目录中，并创建一个 Python 脚本（类似于 update.py）来获取动态数据并将其填充到这些模板中。
2. 类别文件 (__category__.json)：要管理侧边栏中文档的顺序，请在每个文件夹中创建一个 __category__.json 文件。例如：

  pip install aiosql pandas sqlite3 jinja2 shutil

__category__.json 示例:

   mkdocs new mkdocs
   cd mkdocs

---

⚙️ Jinja 的动态数据

为了合并动态内容，例如数据库表，我们使用名为 update.py 的 ?Python 脚本，您可以在存储库中找到该脚本。

此脚本从 SQLite 数据库获取数据并处理存储在 templates 文件夹中的 Markdown 文件。然后，它使用获取的数据更新这些文件，并将它们复制到 docs 文件夹中，为站点渲染做好准备。

此工作流程确保内容保持最新并准备好部署，遵循与我们使用 MkDocs 实现的类似方法。

---

⚙️ Docusaurus：最终工作流程

1. 创建模板：在 docs/template 目录中开发 Markdown 文件。
2. 运行Python脚本：使用脚本将数据动态填充到模板中。
3. 本地预览：运行 npx docusaurus start 预览站点。
4. 构建部署：准备好后，使用 npx docusaurus build 生成静态站点。
5. 部署：在您首选的平台上托管静态文件，例如 AWS S3。

---

？部署

在本节中，我们将介绍使用 AWS S3 进行托管的 MkDocs 和 Docusaurus 的部署过程。虽然这两种工具的部署步骤相同，但安装过程有所不同，MkDocs 基于 Python，Docusaurus 基于 JavaScript。

---

使用 Terraform 进行基础设施设置

要将静态文档站点部署到 AWS S3，我们使用 Terraform 来预置和配置所需的资源。该设置定义了 S3 存储桶，启用静态网站托管，并使用存储桶策略配置公共访问以允许只读访问。您可以在存储库中找到 main.tf 文件。

---

？ S3 部署的关键组件

1. S3 存储桶创建：用于创建将托管文档的 S3 存储桶的资源。
2. 静态网站托管：静态网站托管配置，设置index.html和error.html为主文档和错误文档。
3. 公共访问配置：管理对 S3 存储桶的公共访问，确保将其配置为只读访问。
4. 存储桶策略：允许公众访问从 S3 存储桶检索文档内容。

您可以访问完整的Terraform 文件以及在存储库中部署站点的相应配置：

Terraform 配置文件：

• mkdocs 文件
• docusaurus 文件

自动部署的 GitHub Action 工作流程：存储库中还包含用于自动化部署过程的 CI/CD 管道。

• mkdocs 文件
• docusaurus 文件

GitHub 操作配置
确保在设置 >下的GitHub存储库机密中配置您的AWS凭证。 秘密 > 行动。这将允许 GitHub Actions 安全地访问您的 AWS 账户，并在您将更改推送到主分支时执行将文件上传到 S3 等操作。

---

存储库

下面是部署文档站点的所有代码的链接。如果觉得有用，可以给个star⭐️，关注我即可接收新文章通知。这将帮助我在技术社区中成长并创造更多内容。

• MkDocs 部署：MkDocs 的 GitHub 存储库

罗米门德斯 / 文档即代码 mkdocs

有关如何使用“文档即代码”方法创建文档项目的教程

---

⚙️ 文档即代码教程

？ MkDocs 和 MkDocs-材料

MkDocs 是实现文档门户的绝佳解决方案，可以使用代码轻松更新，帮助您的软件开发项目文档保持最新和版本控制。

在此存储库中，我创建了一个简单的站点来记录数据模型和机器学习项目。

文档将包括图表、表格和架构示例，提供全面且易于理解的指南，指导如何结合其他两个 ?Python 库来实现此框架。

什么是文档即代码？

文档及其更新是许多开发软件的公司的一个重要流程，该流程是使用不同的工具执行的，其中许多是付费解决方案。
因此，最近出现了“doc as code”的概念。这意味着使用软件开发中使用的相同工具和工作流程来管理、版本和......

在 GitHub 上查看

• Docusaurus 部署：Docusaurus 的 GitHub 存储库

罗米门德斯 / 文档即代码 docusaurus

有关如何使用“文档即代码”方法创建文档项目的教程

---

⚙️ 文档即代码教程

？多库龙

Docusaurus 是实现文档门户的绝佳解决方案，可以使用代码轻松更新，帮助您的软件开发项目文档保持最新和版本控制。

在此存储库中，我创建了一个简单的站点来记录数据模型和机器学习项目。

文档将包括图表、表格和架构示例，提供全面且易于理解的指南，指导如何结合其他两个 ?Python 库来实现此框架。

什么是文档即代码？

文档及其更新是许多开发软件的公司的一个重要流程，该流程是使用不同的工具执行的，其中许多是付费解决方案。
因此，最近出现了“doc as code”的概念。这意味着使用软件开发中使用的相同工具和工作流程来管理、版本和部署文档......

在 GitHub 上查看

---

？最终结论：MkDocs 与 Docusaurus

这两种解决方案都很容易实现，但在以下项目中，我们可以探索一些差异，什么是最佳解决方案取决于您可能需要实现的上下文、知识和复杂性。

• ？ 语言和定制： MkDocs 基于 Python，具有简单的 YAML 配置和模板，非常适合快速设置。另一方面，Docusaurus 基于 React，提供高级定制和交互组件，使其更适合需要更多视觉控制的用户。
• ？ 降价和渲染： 两者都使用 Markdown，但 Docusaurus 允许交互元素，使其更适合动态内容。
• ⚙️ 复杂性： Docusaurus 更适合复杂的文档应用程序，例如具有登录系统的应用程序。 MkDocs 更简单，但 Docusaurus 为样式和功能提供了更大的灵活性。
• ？ 社区： Docusaurus 拥有强大的社区，包含 Discord 和 74 个插件，而 MkDocs 则依赖 GitHub 讨论来获得社区支持。
• ☁️ 亚马逊部署： 您可以将静态站点部署到S3，降低部署成本，还可以使用CI/CD进行自动部署。

---

？参考

1. Mkdocs：https://www.mkdocs.org/
2. Mkdocs-Material：https://squidfunk.github.io/mkdocs-material/
3. 图表：https://diagrams.mingrammer.com/
4. Docusaurus：https://docusaurus.io/
5. Jinja：https://jinja.palletsprojects.com/en/stable/
6. Git 书籍 - 什么是 doc as code：https://www.gitbook.com/blog/what-is-docs-as-code
7. 编写文档：https://www.writethedocs.org/guide/docs-as-code/

以上是在 AWS 上部署文档即代码：在 MkDocs 和 Docusaurus 中构建动态文档站点的详细内容。更多信息请关注PHP中文网其他相关文章！