文档即代码的实际应用：记录 Python 库。

文档是帮助您的目标受众了解如何有效使用您的产品的重要资源。高质量的文档不仅传达了产品解决的核心问题，还使用户能够无缝地实现他们想要的结果。

对于开源库和包来说也是如此。清晰且易于访问的文档对于指导开发人员如何将这些工具成功集成到他们的项目中至关重要。

近年来，文档即代码 (DaC) 文档方法已广受欢迎。此方法通过使用开发人员依赖于代码的相同工具和流程，将文档视为软件开发生命周期的基本部分。

这种方法被广泛接受，因为它促进了一致的、版本控制的、易于维护的文档，并与产品一起发展。

什么是文档即代码？

简单来说，DaC 是一种涉及处理和维护文档的方法，就像处理代码一样。

典型的软件开发生命周期涉及 7 个阶段，其中包括以下阶段：

1. 计划
2. 收集需求和分析
3. 设计
4. 编码和实现
5. 代码测试
6. 代码部署
7. 代码维护

因此，DaC 是一种确保文档经历相同阶段的新方法。这可以保持文档的版本并随着软件更改而保持最新。

不使用 DaC 进行部署

使用 DaC 进行部署

虽然本指南可能不会深入探讨 DaC 的理论方面，但您可以探索文档即代码初学者指南文章，其中详细解释了 DaC 背后的概念。

项目概况

本指南涉及使用 Python 进行 DaC 的实际实现。您将学习如何使用 Mintlify 记录开源 Python 库。

Mintlify 是一个静态站点生成器和文档站点，用于面向公众的文档。它易于维护和使用，可满足各种文档需求，例如开发人员文档、API 文档等。它也与 DaC 方法论配合良好。

本教程是有关如何构建和部署 Python 库的现有教程的续集。使用 DaC 方法，您将学习如何记录 Python 库开发的参考教程。

建议您先完成之前的教程，然后再继续。但是，如果您有可用于本教程的现有项目，则可以继续。

项目要求

需要具备 Git 和 GitHub 的基本知识，如何创建 Github 存储库以及如何将代码推送到 GitHub。本教程还需要以下工具：

• Mintlify 帐户： 您需要一个活跃的 Mintlify 帐户来创建文档（指南中将提供步骤）。
• Node.js：您需要 Node.js 版本 18 及更高版本才能安装 Mintlify 并在本地编辑文档。

设置 Mintlify 文档

按照以下步骤使用 Mintlify 设置文档：

1。在 Mintlify 上创建帐户

2。设置您的 Mintlify 帐户：
验证链接将发送到您的邮箱。此链接会将您重定向至以下页面：

3。使用 Github 登录：
第一步需要您使用 Github 帐户登录。

4。为您的文档创建 GitHub 存储库 (repo)：
下一步需要您在 Github 帐户上安装并授权 Mintlify 应用程序。这允许 Mintlify 自动为您的文档创建一个存储库

5。访问您的文档存储库：
上一步为您的文档创建一个新的文档存储库。检查您的 GitHub 存储库中是否有新的文档存储库

将文档添加到您的项目中

下一步是将文档存储库克隆到您的本地环境并将其添加到现有项目中，例如开发人员工具、开源包等。如果您已经完成了上一个教程，您的项目将是 ExchangeLibrary。

按照以下步骤将文档添加到您的项目中：

1。打开终端并使用以下命令克隆文档存储库：

git clone https://github.com/<your github username>/docs 

2。将克隆的 docs 文件夹复制到您的项目。

3。在代码编辑器中打开项目。

您的项目文件结构现在应如下所示：

本地预览文档

Mintlify 允许您在发布文档之前在本地预览文档。请按照以下步骤进行设置：
1.在终端中打开您的项目
2.运行以下命令以全局安装 Mintlify：

git clone https://github.com/<your github username>/docs 

3。切换到项目中的 docs 文件夹：

npm i -g mintlify

4。使用以下命令启动 mintlify 服务器：

cd docs

您应该在终端中看到如下所示的消息：

打开URL即可在本地预览文档。您的文档内容将是 Mintlify 入门文档模板。当您开始编辑文档时，这将会改变。

编写文档

Mintlify 文档由 mint.json 文件提供支持。该文件包含文档的配色方案、分页和导航设置。您可以在项目的 docs 文件夹中找到它。

此外，Mintlify 中的文档文件是用 .mdx 编写的。它几乎与 markdown(.md) 类似，只是它允许特殊的标签和符号。

在本节中，您将学习如何在 mint.json 文件中编辑文档设置，以及如何向文档添加文本和特殊组件。

编辑文档设置

mint.json 文件是一个 JSON 对象，由文档的配色方案、分页、导航设置等组成。以下是可用设置及其含义的列表：

1。配色方案和外观：
此部分用于美化和增强您的文档外观。它用于更改文档的徽标（浅色和深色模式）、图标、标题和配色方案。它从 $schema 键开始到颜色键，如下所示：

mintlify dev

2。导航链接和 CTA 按钮：
此部分用于在文档页面顶部设置导航链接和按钮。以下是导航链接和按钮的示例：

下面的代码为您的 Mintlify 文档设置导航链接和 CTA 按钮：

  "$schema": "https://mintlify.com/schema.json",
  "name": "<your-documentation-title>",
  "logo": {
    "dark": "<logo-for-dark-mode>",
    "light": "<logo-for-light-mode>"
  },
  "favicon": "<link-to-a-favicon>",
  "colors": {
    "primary": "#0D9373",
    "light": "#07C983",
    "dark": "#0D9373",
    "anchors": {
      "from": "#0D9373",
      "to": "#07C983"
    }
  },

3。选项卡和锚点：
选项卡和锚点可用于分别在文档中设置水平和垂直部分。以下是选项卡示例：

下面是锚点的示例：

这些组件的设置由选项卡和锚点键处理。

4。导航设置：
本部分帮助您对文档中的页面进行分组。它是一个由组键和页面数组组成的数组，其中按顺序添加该组的页面。以下是如何添加的示例：

git clone https://github.com/<your github username>/docs 

上面的设置将转换为下图：

页面（简介等）是项目文档文件夹中的 .mdx 文件。

5。嵌套导航：
嵌套导航通常用于在文档中创建小节。以下是嵌套导航的示例：

下面是在 Mintlify 上设置嵌套导航的示例代码：

npm i -g mintlify

上面的代码将一个部分/组嵌套在另一个部分中。图标键在网页上呈现时用图标美化章节标题。

6。页脚设置：
footerSocials 键用于添加与文档相关的社交媒体帐户。下面是一个例子：

如何添加内容

Mintlify 文档指导您如何向文档添加内容。我建议您查看文档以了解如何向文档添加不同的内容。

查看此示例文档，获取有关如何构建自己的文档的灵感。

文档写作技巧

以下一些提示可帮助您编写清晰且用户友好的文档：

1. 尽可能直接： 避免没有任何价值的无关信息。您的文档适用于想要在下一个项目中使用您的包或工具的开发人员，因此仅向他们展示实现此目标所需的内容。

2。添加工具的描述或概述：
在详细介绍如何使用工具之前，请简要描述一下您的工具是什么以及它解决的问题。这应该在第一页。

3。添加足够的代码示例：
这将帮助他们了解如何使用您的工具，而不会出现不必要的错误。有关安装、身份验证、响应示例、方法参数等的代码示例非常重要。

4。错误和异常：
这将有助于用户调试。添加一个页面来描述用户在使用您的工具时可能遇到的错误类型。还显示了这方面的代码示例。

将项目推送到Github

按照以下步骤将项目推送到Github：

1。在项目中打开 git bash 终端，然后使用以下命令切换到 docs 文件夹：

git clone https://github.com/<your github username>/docs 

2。使用以下命令从此文件夹中删除 git：

npm i -g mintlify

此命令会从 docs 文件夹中删除 .git，以避免您要将整个项目推送到 Github 时出现问题。

3。将项目推送到 GitHub。

部署文档

按照以下步骤在 Mintlify 上部署您的文档：
1.登录您的 Mintlify 仪表板
2.单击“设置”选项卡

3.将您的 Mintlify Github 存储库更改为您项目的存储库

4.激活 monorepo 开关。这表示 docs 文件夹存在于单个存储库中的另一个项目中。

5。在出现的新字段中输入 **docs 作为 mint.json 文件的路径。**

6。单击“保存”按钮保存更改。

您的文档可以通过仪表板概述选项卡中显示的链接访问

更新项目

您最有可能对项目进行更改，并且可能需要重新部署它。

在项目中进行任何更新后，请确保将更改推送到 Github。 Mintlify 会自动获取新的更改并立即更新您的文档。

结论

在本教程中，您学习了如何使用文档即代码方法为 Python 库构建文档。

文档即代码促进项目上的协作和持续集成。当谈到开源时，文档即代码允许人们在项目上无缝协作，同时维护最新的适当文档。

有不同的 REST API，没有 SDK 或编程库。选择您感兴趣的一个并创建类似的东西。

继续建设？‍？！

常见问题解答

如何测试我的文档？

此功能通常用于具有多个贡献者的大型项目。当向项目发出拉取请求时，文档测试会自动运行。如果测试成功，则合并更改。阅读本指南，了解 Swimm 如何提供自动文档测试以了解更多信息。

我可以用其他编程语言复制这个项目吗？
是的，你可以。请按照本指南中的步骤操作，以您的首选语言获得类似的结果。

除了 Mintlify 之外还有其他文档站点吗？
是的，您还可以使用其他文档站点。其中包括：Gitbook、Readme、Docusaurus 等

以上是文档即代码的实际应用：记录 Python 库。的详细内容。更多信息请关注PHP中文网其他相关文章！