Sphinx-Multiversion 使用教程

7.7. Sphinx-Multiversion 使用教程#

Sphinx extension for building self-hosted versioned docs.

项目地址: https://gitcode.com/gh_mirrors/sp/sphinx-multiversion

7.7.1. 项目介绍#

Sphinx-Multiversion 是一个用于构建自托管版本化文档的 Sphinx 扩展。它旨在提供一个干净的实现，尽量避免与 Sphinx 内部机制的直接交互。通过这个扩展，用户可以轻松地为不同版本的文档生成独立的页面，方便用户在不同版本之间进行切换和比较。

7.7.2. 项目快速启动#

安装

首先，确保你已经安装了 Python 和 pip。然后，使用以下命令安装 sphinx-multiversion：

pip install sphinx-multiversion

配置

在你的 Sphinx 项目根目录下，找到 conf.py 文件，并添加以下配置：

extensions = [
    'sphinx_multiversion',
]
html_sidebars = {
    '**': [
        'versions.html',
    ],
}

生成文档

使用以下命令生成版本化的文档：

sphinx-multiversion source build/html

这将生成一个包含所有版本文档的目录结构，用户可以通过侧边栏轻松切换不同版本的文档。

7.7.3. 应用案例和最佳实践#

应用案例

  • 开源项目文档管理：许多开源项目需要为不同版本的代码提供相应的文档。使用 sphinx-multiversion 可以轻松管理这些文档，确保每个版本的文档都能独立访问。

  • 企业内部文档系统：企业内部可能有多版本的 API 文档或用户手册，使用 sphinx-multiversion 可以方便地管理和维护这些文档。

最佳实践

  • 定期更新文档：确保每个版本的文档都能及时更新，避免过时的信息误导用户。

  • 版本控制：使用 Git 或其他版本控制系统管理文档源文件，确保每个版本的文档都能追溯到具体的代码提交。

7.7.4. 典型生态项目#

  • Sphinx：sphinx-multiversion 是基于 Sphinx 构建的，因此与 Sphinx 生态系统紧密结合。

  • Read the Docs：虽然 sphinx-multiversion 主要用于自托管文档，但它也可以与 Read the Docs 结合使用，提供版本化的在线文档。

  • Git：版本控制是 sphinx-multiversion 的核心功能之一，因此与 Git 的集成是必不可少的。

通过以上步骤，你可以轻松地使用 sphinx-multiversion 为你的项目生成版本化的文档，并确保用户能够方便地访问不同版本的文档。

目录