夜雨聆风
使用Sphinx构建软件说明书(6):将构建好的文档托管到readthedoc
使用Sphinx构建软件说明书（6）：将构建好的文档托管到readthedoc
微信公众号：生信小知识
关注可了解更多的生物信息学教程及知识。问题或建议，请公众号留言;
目录
前言1. readthedoc简介2. 托管 Github 上文档3. readthedoc配置文件后记
前言
我决定使用Sphinx对开发的软件包写一个说明书，这里记录我学习Sphinx的记录。
所有知识来源：
-
https://www.osgeo.cn/sphinx-note/intro.html -
Sphinx 1.3.1 中文手册 (推荐查看)
已发布教程：
前面的教程，已经让我们掌握了构建工具的使用方法。接下来我们则主要学习下编写文档语言—— reStructuredText (rst)
1. readthedoc简介
ReadTheDocs 是一个提供了托管服务的平台。我们可以把生成的 Sphinx 网页托管到这个平台上进行在线发布。首先我们需要在这个平台注册账号，不过也可以选择关联我们的 Github 账号。
我们首先登录网站：https://about.readthedocs.com/
这里我选择关联我的 Github 账号登录：
然后我们就可以登录到主界面。
2. 托管 Github 上文档
-
我们首先点击添加新项目：
-
然后我们输入自己想要托管的项目，当你输入后，会自动跳出符合要求存放在 Github 上的项目：
-
选中项目后，点击 “
Continue” 选择继续，然后我们需要设置一些基础设置，不过一般不需要额外修改。这里根据自己的情况做选择即可：
-
我直接点击 “下一页”，然后需要我们准备一个配置文件
.readthedocs.yamml文件。通过这个文件，readthedoc网站才知道去哪里寻找我们的文档内容。关于这个文档具体设置可以看后面章节。这里已经准备好，我们直接点击 “This file exists” 进行下一步：
3. readthedoc配置文件
具体的设置我们可以在这里查询：https://docs.readthedocs.com/platform/stable/config-file/v2.html
这里提供我的模板供大家参考：
# Read the Docs configuration file
# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
# Required
version: 2
# Set the OS, Python version, and other tools you might need
build:
os: ubuntu-24.04
tools:
python: "3.13"
# Build documentation in the "docs/" directory with Sphinx
sphinx:
configuration: docs/source/conf.py
# Optionally, but recommended,
# declare the Python requirements required to build your documentation
# See https://docs.readthedocs.io/en/stable/guides/reproducible-builds.html
python:
install:
- requirements: docs/requirements.txt
其中基本上只需要修改 sphinx/configuration 项目，用于指定配置文件即可。其他的几乎不用修改。
另外，对于如果需要安装其他插件或者其他主题，可以通过 python/install/requirements 项目指定即可。我的 docs/requirements.txt 文件内容如下：
sphinx-rtd-theme
后记
这里我们学习了一些构建文档时的语言 reStructuredText ，至此我们已经完整掌握了构建工具和语法的使用，接下来我们即将学习如何将构建好的文档托放到网络~
