返回

文档开发必备：Github + Sphinx + Read the Docs 实战进阶指南

开发工具

文档自动化部署进阶：轻松管理和维护您的文档

简介

作为现代软件开发流程中不可或缺的一部分，文档对于有效沟通、协作和知识共享至关重要。为了使文档管理更加轻松便捷，自动部署功能应运而生，让您能够无缝更新文档，同时节省宝贵的时间和精力。本文将深入探究如何自动将文档部署到 Read the Docs 平台，从而简化您的文档更新流程。

满足文档基本要求

在开始自动化部署之前，您的文档需要满足以下基本要求：

  • 格式： 使用 Markdown 或 ReStructuredText 格式，这是 Read the Docs 支持的标准文档格式。
  • 主题： 选择一个合适的 Sphinx 或 Read the Docs 主题，为您的文档提供专业的外观和感觉。
  • 结构和语言： 确保文档内容结构清晰、语言流畅，易于理解和浏览。

Github 配置自动化部署

自动化部署的关键一步是设置 Github 项目配置。为此，您需要创建 .readthedocs.yml 文件并添加以下内容：

# Read the Docs configuration file
# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details

version: 2

build:
  source: docs
  requirements: requirements.txt

deploy:
  provider: readthedocs.org
  username: <your_username>
  password: <your_password>
  # The following line determines the branch of the repo that is deployed
  # to the Read the Docs server.
  branch: master

请将 <your_username> 和 <your_password> 替换为您的 Read the Docs 凭据。将此文件推送到您的 Github 项目，即可完成 Github 配置。

Read the Docs 设置项目

接下来，您需要在 Read the Docs 网站上设置您的项目：

  1. 登录 Read the Docs 网站。
  2. 点击 "New Project" 按钮。
  3. 选择 "Import a Project" 选项。
  4. 选择 "Github" 作为源代码托管平台。
  5. 输入 Github 项目的 URL。
  6. 点击 "Import" 按钮。

构建和发布文档

设置完成后，您可以构建和发布文档：

  1. 在 Github 项目中，点击 "Actions" 标签。
  2. 在 "Actions" 标签中，找到 "Read the Docs" 工作流。
  3. 点击 "Run workflow" 按钮。
  4. 等待工作流运行完成。
  5. 文档构建完成后，点击 "View Docs" 按钮即可查看文档。

结论

通过实现文档自动化部署，您不仅可以节省宝贵的时间和精力，还可以确保文档始终是最新的。自动部署功能简化了更新过程，让您专注于更重要的任务，提升工作效率。

常见问题解答

  • 我应该使用 Markdown 还是 ReStructuredText 格式？

两种格式都可以，取决于您的偏好。Markdown 更简单、更易于编写，而 ReStructuredText 更强大、更灵活。

  • 如何选择一个合适的主题？

Read the Docs 提供了各种主题，每个主题都有自己的特点。选择一个符合您的文档外观和感觉的主题。

  • 我可以从 Github 推送我的文档吗？

是的，您可以通过 git push 命令将文档推送到 Github。在推送到 Read the Docs 之前，请确保 origin 远程指向您的 Github 项目。

  • 我可以通过命令行构建和部署文档吗？

是的，您可以使用 readthedocs-build 命令从命令行构建和部署文档。

  • 如何更新自动部署配置？

只需编辑 .readthedocs.yml 文件，添加或更新配置设置，然后将更改推送到 Github。