前言
前两年自己曾制作了一个静态博客网站部署到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/indexPyzjr/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博客