sphinx+reStructuredText写文档、发布网站 (源码+发布效果)

sphinx+reStructuredText写文档、发布网站

点击这里跳转本文的发布地址

点击这里跳转本文的github源码地址

1. 概念解释

摘抄中文维基词条

1. sphinx: Sphinx是Python社区编写和使用的文档生成器。它是用Python编写的，也可以在其他环境中使用。
   Sphinx将reStructuredText文件转换为HTML网站和其他格式，包括PDF、EPUB、Texinfo和man。
2. reStructuredText: reStructuredText（RST、ReST或reST）是一种用于文本数据的文件格式，主要用于 Python 编程语言社区的技术文档。

简单地说, reStructuredText是一种标记语言 (类似html) ,而sphinx把组织起来的reStructuredText生成为文档. 事实上, python相关的文档都是通过这种方式生成的.

2. 环境安装

需要安装

1. sphinx
2. sphinx-autobuild 自动编译工具, 开启后无需手动编译
3. furo 一个sphinx主题

pip install sphinx sphinx-autobuild furo
1

3. 快速生成模板文档

1. 创建一个放置文档的文件夹, 可命名为docs

   mkdir docs && cd docs
   1

2. 在文件夹下使用sphinx命令快速构建一个初始文档, 输入该命令后会有几次交互, 可以按照自己的意愿填入相应的值, 也可不填后续再改动

   sphinx-quickstart
   1

   下面按照 源文件生成目录分离 项目名sample 项目作者hongyuan 项目语言zh来快速构建一个文档
   
   若按照上文顺序, 生成的文件目录如下:

   docs
   ├── Makefile
   ├── build
   ├── make.bat
   └── source
       ├── _static
       ├── _templates
       ├── conf.py
       └── index.rst
   1
   2
   3
   4
   5
   6
   7
   8
   9

3. 编译文档: 将source中的源文件编译到build文件夹中的html文件夹

   sphinx-build ./source ./build/html
   1

4. 打开文档: 打开docs/build/html中的index.html文件, 即可看到模板文档, 样式如下:
   

4. 修改模板文档

在本节中我们对第三节生成的模板文档进行修改, 修改的点有以下几个:

1. 增加页面
2. 增加文档基本内容, 包括标题、正文、列表、表格、图片、公式
3. 修改文档主题

为了简便起见, 我们使用自动编译, 在docs文件夹下打开终端, 输入

sphinx-autobuild ./source ./build/html
1

该命令将source文件夹中的文件自动编译到build/html中

4.1 增加页面

本节我们增加两个页面, 分别为“第一章”和“第二章”, 并将两个页面索引在主页中, 增加后效果如下

1. 在docs/source文件夹即index.rst同级文件夹下, 创建名为“第一章.rst”的文件; 在同级文件夹下创建名为“第二章.rst”的文件
2. 打开“第一章.rst”, 将内容改为

   第一章
   ================
   1
   2

   “第二章.rst”内容同理
3. 在docs/source文件夹下, 我们将index.rst的内容改为

   欢迎来到示例文档
   ==================================
   
   .. toctree::
   	:maxdepth: 2
   	:caption: 目录:
   
   	第一章
   	第二章
   1
   2
   3
   4
   5
   6
   7
   8
   9

现在打开 (刷新) index.html, 页面已经增加成功

4.2 增加文档基本内容

4.2.1 标题

在4.1中实际上我们已经增加过目录, 增加目录的格式非常简洁, 我们只要在文本下加上多个连续的符号 (如+, =, -, #, @等) 即可, 同级标题使用同样的连续符号即可.
示例

第一节
---------

第二节
---------

2.1 小节一
==============

2.2 小节二
++++++++++++++++
1
2
3
4
5
6
7
8
9
10
11

注意空行

4.2.1 正文

正文可在文档页面的任何地方书写, 使用双星号加粗, 单星号加斜, 我们在第一章中加一点内容:

**这里是粗体**, *这里是斜体*, 这里是普通文本.
1

4.2.2 链接

我们在第一章中加入python文档的链接, 注意文本和链接之间的空格, 以及末尾的下划线

这里是 `Python文档链接 `_
1

4.2.2 列表

列表格式与markdown相似, 我们在第一节中加入一个有序列表和一个无序列表

1. 第一条
2. 第二条
3. 第三条

* 第一条
* 第二条
* 第三条
1
2
3
4
5
6
7

4.2.3 增加批注

我们在第二节增加一个批注

.. note::
   此处是一个标注
1
2

4.2.4 表格

在小节一增加一个表格:

+------+------+------+
|   A  |   B  |   C  |
+======+======+======+
| 1A   | 1B   | 1C   |
+------+------+------+
| 2A   | 2B   | 2C   |
+------+------+------+
1
2
3
4
5
6
7

4.2.5 图片

插入图片格式如下

.. image:: img_path
1

我们放一张图片在/source/_stastic下, 然后将其放入小节一

.. image:: ./_static/sample.png
1

4.2.6 公式

我们在小节二中插入一个数学公式

.. math::

	x = y \times z + \sum_{(i, j)}f(i, j)
1
2
3

4.3 修改文档主题

我们在上文已经安装过了furo主题, 现在我们将文档的主题替换为furo.
打开和index.rst同级目录下的conf.py文件, 将html_theme的内容修改为“furo”, 即

html_theme = "furo"
1

5. 发布文档

可以通过readthedocs网站免费发布文档, 点击这里跳转本文的发布地址

5.1 写配置

首先在docs目录中创建一个名为.readthedocs的配置文件, 写入以下内容

version: 2

formats:
  - epub

build:
  os: ubuntu-20.04
  tools:
    python: "3.9"
    # nodejs: "16"
    # rust: "1.55"
    # golang: "1.17"
sphinx:
   configuration: source/conf.py
python:
   install:
   - requirements: requirements.txt
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

然后在docs目录中创建一个名为requirements.txt写我们项目需要的依赖, 我们只安装了一个furo主题, 因此写入furo即可

5.2 上传至github

不做介绍

5.3 readthedocs发布

1. https://readthedocs.org/注册账号
2. 在账号中导入gitub库
3. 编译
4. 打开文档