前言
前两年自己曾制作了一个静态博客网站部署到github上,但因为考研还有换了电脑,当时弄的环境早就不会了,看了很多的制作网站的方法,但对于我这个小白来说太复杂了。最近这些天因为查torch的函数,看到了readthedocs的网站,也想给我自己的python库写一个文档,顺便可以用于记录我的学习经历。
一些必备的环境:git,trae(或vscode),Anaconda
创建工程
我们首先创建一个专门的环境:
python
conda create -n zjrdocx python=3.8
激活环境:
python
conda activate zjrdocx
然后安装sphinx
python
pip install -i https://pypi.tuna.tsinghua.edu.cn/simple sphinx
然后我们创建一个工程用于测试,这里我的路径为:E:\icetea
python
(zjrdocx) C:\Users\ASUS>E:
(zjrdocx) E:\>cd \icetea
进入上面的文件夹后,在命令行中输入下面的命令,创建一个Sphinx的项目框架
python
sphinx-quickstart
然后接下来会输入一些信息,比如项目的名字,作者,版本号等等,以及所用的语言,这儿用中文就输入zh_CN,详细内容可以看看下面。
python
(zjrdocx) E:\icetea>sphinx-quickstart
Welcome to the Sphinx 7.1.2 quickstart utility.
Please enter values for the following settings (just press Enter to
accept a default value, if one is given in brackets).
Selected root path: .
You have two options for placing the build directory for Sphinx output.
Either, you use a directory "_build" within the root path, or you separate
"source" and "build" directories within the root path.
> Separate source and build directories (y/n) [n]: y
The project name will occur in several places in the built documentation.
> Project name: icetea
> Author name(s): Auorui
> Project release []: v1.0
If the documents are to be written in a language other than English,
you can select a language here by its language code. Sphinx will then
translate text that it generates into that language.
For a list of supported codes, see
https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-language.
> Project language [en]: zh_CN
打开项目管理器,如下所示就是创建好了

然后输入下面指令编译一下
python
make html
输出如下编译结果
python
Running Sphinx v7.1.2
loading translations [zh_CN]... done
making output directory... done
building [mo]: targets for 0 po files that are out of date
writing output...
building [html]: targets for 1 source files that are out of date
updating environment: [new config] 1 added, 0 changed, 0 removed
reading sources... [100%] index
looking for now-outdated files... none found
pickling environment... done
checking consistency... done
preparing documents... done
copying assets... copying static files... done
copying extra files... done
done
writing output... [100%] index
generating indices... genindex done
writing additional pages... search done
dumping search index in Chinese (code: zh)... done
dumping object inventory... done
build succeeded.
The HTML pages are in build\html.
进入此路径,点击index.html

默认的效果就是这样的,

安装autobuild工具
刚刚使用的make html的方法编译,在编译完后还需要打开html来查看。这里要换成采用在浏览器中通过ip地址的方式来查看,就需要安装autobuild工具。
python
pip install -i https://pypi.tuna.tsinghua.edu.cn/simple sphinx-autobuild
然后使用下面的指令来进行编译
python
sphinx-autobuild source build/html
在浏览器中打开http://127.0.0.1:8000。

以上的测试效果,使用的是默认的主题,这里我们可以换一个好看的主题,需要先到Sphinx的官网Sphinx Themes Gallery查看:

这里我们选用的是Read the Docs,根据里面的内容安装主题:
python
pip install -i https://pypi.tuna.tsinghua.edu.cn/simple sphinx_rtd_theme
然后打开./icetea/source/conf.py 文件,将html_theme修改为'sphinx_rtd_theme'
python
html_theme = 'sphinx_rtd_theme'
然后重新自动编译
python
sphinx-autobuild source build/html

修改文档格式
Sphinx默认是只支持reST格式的文件,reST的使用语法:reStructuredText 简介
Sphix不支持markdown,如果要使用markdown格式的文档,还要安装markdown支持工具,安装命令如下:
python
pip install -i https://pypi.tuna.tsinghua.edu.cn/simple recommonmark
pip install -i https://pypi.tuna.tsinghua.edu.cn/simple sphinx_markdown_tables
然后修改conf.py,添加上一下内容
python
extensions = ['recommonmark','sphinx_markdown_tables']
现在文档文件可以使用markdown格式,但文档的配置文件index.rst还是要使用reST格式。
修改文档层次
我们打开Trae,打开工程目录,然后修改./icetea/source/index.rst文件,修改maxdepth控制文档目录树的显示深度。然后添加你需要目录以及一个index文件。

在Pyzjr及其子目录下需要创建index.rst文件,其基本的构造如下所示:

Pyzjr/index.rst:
python
Pyzjr 文档中心
===============
.. toctree::
:maxdepth: 2
:caption: 核心文档:
examples/index
tutorials/index
vision/index
Pyzjr/vision/index.rst
python
视觉模块
=======
.. toctree::
:maxdepth: 2
image_processing
object_detection
其他的省略,我们再次编译一下,这样就没什么问题了。


这下没什么问题,后面只需慢慢补充内容就可以了。
托管代码到Gitee
首先创建一个同名的仓库,然后通过git上传代码。

在上传文件之前,写一个.gitigore文件忽略build文件夹。
python
touch .gitignore
通过记事本打开,输入
python
build/
接着通过git指令来将文件上传到仓库
python
git status
python
git add -A
git commit -m "first commit"
git remote add origin https://gitee.com/zeng-junrui/icetea.git
git push -u origin "master"
如果出现了error: remote origin already exists.
可以运行
python
git remote rm origin
删除关联的origin的远程库
python
$ git push -u origin "master"
Enumerating objects: 20, done.
Counting objects: 100% (20/20), done.
Delta compression using up to 16 threads
Compressing objects: 100% (18/18), done.
Writing objects: 100% (20/20), 3.21 KiB | 548.00 KiB/s, done.
Total 20 (delta 0), reused 0 (delta 0), pack-reused 0 (from 0)
remote: Powered by GITEE.COM [1.1.5]
remote: Set trace flag 5741e7be
To https://gitee.com/zeng-junrui/icetea.git
* [new branch] master -> master
branch 'master' set up to track 'origin/master'.
部署到ReadtheDocs
Add project - Read the Docs Community
这里选择手动导入

然后,这里说是要在根目录添加一个文件.readthedocs.yaml文件,我们按照要求添加即可。

出现了错误
看了一下原来是.readthedocs.yaml文件里面的路径错了,修正后强制上传文件即可。
python
git add -A
git commit -m "修改"
git push --force origin master
然后又出错了,我看了一下,原来是没有安装recommonmark,现在下面修改一下.readthedocs.yaml
python
# Required
version: 2
# Set the OS, Python version, and other tools you might need
build:
os: ubuntu-24.04
tools:
python: "3.8"
# Build documentation in the "docs/" directory with Sphinx
sphinx:
configuration: 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: source/requirements.txt
并且在source文件夹下创建requirements.txt文件,填入:
python
recommonmark
sphinx_markdown_tables
sphinx
sphinx_rtd_theme
终于完成了,让我们来看看最终的效果吧:Welcome to icetea's documentation!

参考资料
详细的视频教程:Sphinx+gitee+ReadtheDocs搭建在线阅读文档系统_哔哩哔哩_bilibili
视频对应的图文教程(本文亦可):Sphinx+gitee+Read the Docs搭建在线文档系统-CSDN博客
其他:十分钟拥有你的私人博客!使用readthedocs和mkdocs完成你的文档托管。-CSDN博客