Sphinx和ReadtheDocs构建一个文档网站

前言

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

工作台 - Gitee.com

首先创建一个同名的仓库,然后通过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博客

搭建Sphinx --- Python 1.0.0 documentation

https://zhuanlan.zhihu.com/p/380889131

相关推荐
典学长编程4 小时前
高效学习之一篇搞定分布式管理系统Git !
大数据·git·搜索引擎
G皮T2 天前
【Elasticsearch】自定义评分检索
大数据·elasticsearch·搜索引擎·查询·检索·自定义评分·_score
G皮T3 天前
【Elasticsearch】深度分页及其替代方案
大数据·elasticsearch·搜索引擎·scroll·检索·深度分页·search_after
G皮T3 天前
【Elasticsearch】检索排序 & 分页
大数据·elasticsearch·搜索引擎·排序·分页·检索·深度分页
G皮T3 天前
【Elasticsearch】检索高亮
大数据·elasticsearch·搜索引擎·全文检索·kibana·检索·高亮
Leon.ENV3 天前
meilisearch-轻量级搜索引擎
搜索引擎
小袁拒绝摆烂4 天前
ElasticSearch快速入门-1
大数据·elasticsearch·搜索引擎
阿里云大数据AI技术5 天前
AI搜索 MCP最佳实践
数据库·人工智能·搜索引擎
xixi_6665 天前
文档全文搜索引擎:AnyTXT Searcher
搜索引擎