在本文中，我将指导您一步一步创建一个适用于任何项目的动态文档站点，您可以在其中将文档连接到数据库以提取和显示数据，确保信息始终是最新的。我们还将探索如何使用 AWS.
自动化整个流程，从内容生成到云中部署该解决方案包括对图表和图表的支持、使用 GitHub Actions 中简单工作流程的持续集成 (CI/CD) 以及使用 Terraform 的自动部署。让我们开始吧！
文档及其更新是许多开发软件的公司的重要流程，通常使用不同的工具进行，其中许多是付费解决方案。
因此，最近出现了“doc as code”的概念。这意味着使用软件开发中使用的相同工具和工作流程来管理、版本和部署文档。
这种方法不仅可以更好地跟踪文档，还可以促进其维护，并确保与软件开发中使用的相同最佳实践保持一致，不仅在代码中，而且在文档中。
对于这些网站的开发，有必要了解一些允许我们实施这种方法的实践和工具。以下是本教程中要涵盖的最重要方面的详细列表。
MkDocs 是一个用 ?Python 编写的静态站点生成器，专为文档项目而设计。其目标是简化使用 Markdown 文件创建文档，这些文件易于编写和阅读。
通过最少的配置，MkDocs 将 Markdown 文件转换为可导航且结构良好的文档网站，使其成为想要保持文档最新的开发人员和团队的理想选择。
MkDocs Material 是 MkDocs 的高级主题，遵循 Google 的 Material Design 指南。
Mermaid 是一个 JavaScript 库，用于从文本创建图表。通过与 MkDocs Material 集成，Mermaid 允许您在文档中生成可视化效果，例如流程图、实体关系图和文档中的其他图表，而无需外部工具。
Jinja 是一个库，允许将 Python 字典中的变量和数据嵌入到 HTML 中，使网页动态化。该库通常用于生成动态 HTML 和发送个性化电子邮件。
Docusaurus 是 Meta 于 2007 年开发的一个开源项目，它以快速高效的方式简化了文档网站的创建、部署和维护。它允许使用 Markdown 和 MDX 来编写内容，而其基于 React 的核心可以完全自定义样式，以满足项目的特定需求。
此外，Docusaurus 通过 @docusaurus/theme-mermaid 插件支持 Mermaid，从而可以直接在文档中包含图表和图表。
图表即代码是一种允许您通过代码而不是使用传统图形工具来创建图表的方法。您无需手动构建图表，而是在文本文件中编写代码来定义图表的结构、组件和连接。
然后该代码被转换为图形图像，从而更容易在软件项目中集成和记录。它对于以编程方式创建和更新架构图和流程图特别有用。
如前所述，图表允许您使用主要云技术的图标生成蓝图。这些图表的表示是通过节点完成的，在我们的示例中，我们将使用所有与云相关的节点和 AWS 服务。
有关我如何创建它的更多详细信息，您可以阅读我关于图表即代码的文章，完整的实现可以在此存储库中找到：
罗米门德斯
/
图表即代码
图表即代码是一种允许您通过代码而不是传统图形工具创建图表的方法。您可以在文本文件中编写代码来定义图表的结构、组件和连接，而不是手动构建图表。
然后，该代码被转换为图形图像，从而更容易在软件项目中集成和记录，这对于以编程方式创建和更新架构和流程图特别有用。
Diagrams 是一个 ?Python 库，它实现了图表即代码方法，使您能够通过代码创建架构基础设施图和其他类型的图表。借助图表，您只需几行代码即可轻松定义云基础设施组件（例如 AWS、Azure 和 GCP）、网络元素、软件服务等。
在此用例中，我将为 机器学习项目 创建一个文档网站，涉及 ?医院数据。目标是最初使用 MkDocs 构建一个交互式文档站点，然后将其迁移到 Docusaurus。该网站将包括静态和动态组件以满足特定要求，例如嵌入可视化图表和从 SQLite 数据库动态更新数据。
因此，我们的文档网站将包含以下页面：
在本节中，我们将逐步完成使用 MkDocs 从头开始设置文档项目的步骤，并解释其组织的目录结构。
首先，您需要安装以下 ?Python 库：
安装 MkDocs 和材质
pip install mkdocs mkdocs-material
安装额外的库以启用动态内容更新
pip install aiosql pandas sqlite3 jinja2 shutil
初始化项目
首先创建一个新的 MkDocs 项目。在终端中运行以下命令：
mkdocs new mkdocs cd mkdocs
此命令创建一个具有默认结构的基本 MkDocs 项目。
探索目录结构
创建 MkDocs 站点后，您需要添加以下文件和文件夹，因为默认情况下不包含它们。
请记住，本文末尾提供了存储库的链接供您参考，下面将详细解释每个组件。
pip install mkdocs mkdocs-material
| 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.yml 文件开始逐步配置它。该文件定义文档站点的结构和设置。它的结构如下：
mkdocs.yml
pip install mkdocs mkdocs-material
在此配置文件中，您主要可以在nav部分中看到可从菜单访问的页面。然后，我们指定 Mermaid 扩展，这将在下一节中解释。最后，主题部分应用Material主题，启用该库中可用的样式和组件。
如前所述，Mermaid 是一个 JavaScript 库，用于从文本创建图表和图表。下面，我们将看到一些例子。在我们的例子中，我们将使用它在文档的表页面上生成实体关系图（ERD）。
在存储库中，您将能够了解如何根据 Synthea 官方文档中的实体关系图 (ERD) 构建此代码。您还可以在以下链接中查看表格页面的示例：tables.md.
为了为我们的文档站点启用动态内容生成，我们将使用 Jinja 来处理模板并用实际数据替换占位符。以下是逐步细分：
设置模板文件夹
创建一个名为 templates 的文件夹来存储站点的所有 Markdown 文件。这些文件应包含占位符。例如，在index.md中，您可能有像{{database.version_date}}和{{database.version}}这样的占位符。
使用占位符
占位符是 Markdown 文件中的动态变量。这些变量将使用Python字典自动更新以注入相关数据。
使用 update.py 生成动态内容
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
流程如下：
? 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
这样，文档始终反映最新数据，根据数据库中的实际内容显示动态示例。
在以下部分中，我将提供有关如何使用 Docusaurus 实现文档站点的详细步骤和见解。这包括设置、自定义和部署选项。
要开始使用 Docusaurus，我们遵循快速设置过程，该过程与我们用于 MkDocs 的步骤非常相似，但使用不同的工具。
pip install mkdocs mkdocs-material
pip install aiosql pandas sqlite3 jinja2 shutil
mkdocs new mkdocs cd mkdocs
配置文件 docusaurus.config.js 是我们自定义标题、主题、导航以及启用 Mermaid 等功能以进行图表渲染的地方。
启用美人鱼的示例片段：
pip install mkdocs mkdocs-material
为了自定义主页，我们修改 src/components/HomepageFeatures/index.js 文件。在这里，您可以调整 FeatureList 对象来更新主页上显示的功能。
就像在 MkDocs 中一样，Docusaurus 支持 Markdown 文件 作为内容，我们按如下方式组织结构：
pip install aiosql pandas sqlite3 jinja2 shutil
__category__.json 示例:
mkdocs new mkdocs cd mkdocs
为了合并动态内容，例如数据库表，我们使用名为 update.py 的 ?Python 脚本，您可以在存储库中找到该脚本。
此脚本从 SQLite 数据库获取数据并处理存储在 templates 文件夹中的 Markdown 文件。然后，它使用获取的数据更新这些文件，并将它们复制到 docs 文件夹中，为站点渲染做好准备。
此工作流程确保内容保持最新并准备好部署，遵循与我们使用 MkDocs 实现的类似方法。
在本节中，我们将介绍使用 AWS S3 进行托管的 MkDocs 和 Docusaurus 的部署过程。虽然这两种工具的部署步骤相同，但安装过程有所不同，MkDocs 基于 Python，Docusaurus 基于 JavaScript。
要将静态文档站点部署到 AWS S3，我们使用 Terraform 来预置和配置所需的资源。该设置定义了 S3 存储桶，启用静态网站托管，并使用存储桶策略配置公共访问以允许只读访问。您可以在存储库中找到 main.tf 文件。
您可以访问完整的Terraform 文件以及在存储库中部署站点的相应配置：
Terraform 配置文件：
自动部署的 GitHub Action 工作流程：存储库中还包含用于自动化部署过程的 CI/CD 管道。
GitHub 操作配置
确保在设置 >下的GitHub存储库机密中配置您的AWS凭证。 秘密 > 行动。这将允许 GitHub Actions 安全地访问您的 AWS 账户，并在您将更改推送到主分支时执行将文件上传到 S3 等操作。
下面是部署文档站点的所有代码的链接。如果觉得有用，可以给个star⭐️，关注我即可接收新文章通知。这将帮助我在技术社区中成长并创造更多内容。
罗米门德斯
/
文档即代码 mkdocs
MkDocs 是实现文档门户的绝佳解决方案，可以使用代码轻松更新，帮助您的软件开发项目文档保持最新和版本控制。
在此存储库中，我创建了一个简单的站点来记录数据模型和机器学习项目。
文档将包括图表、表格和架构示例，提供全面且易于理解的指南，指导如何结合其他两个 ?Python 库来实现此框架。
文档及其更新是许多开发软件的公司的一个重要流程，该流程是使用不同的工具执行的，其中许多是付费解决方案。
因此，最近出现了“doc as code”的概念。这意味着使用软件开发中使用的相同工具和工作流程来管理、版本和......
罗米门德斯
/
文档即代码 docusaurus
Docusaurus 是实现文档门户的绝佳解决方案，可以使用代码轻松更新，帮助您的软件开发项目文档保持最新和版本控制。
在此存储库中，我创建了一个简单的站点来记录数据模型和机器学习项目。
文档将包括图表、表格和架构示例，提供全面且易于理解的指南，指导如何结合其他两个 ?Python 库来实现此框架。
文档及其更新是许多开发软件的公司的一个重要流程，该流程是使用不同的工具执行的，其中许多是付费解决方案。
因此，最近出现了“doc as code”的概念。这意味着使用软件开发中使用的相同工具和工作流程来管理、版本和部署文档......
这两种解决方案都很容易实现，但在以下项目中，我们可以探索一些差异，什么是最佳解决方案取决于您可能需要实现的上下文、知识和复杂性。
以上是在 AWS 上部署文档即代码：在 MkDocs 和 Docusaurus 中构建动态文档站点的详细内容。更多信息请关注PHP中文网其他相关文章！
