Sphinx：修订间差异

2022年3月31日 (四) 16:16的最新版本

Sphinx是用于创建文档的工具。它最初是为Python文档创建的，也可以在其他环境中使用。Sphinx使用 reStructuredText 作为标记语言，可输出格式包括HTML、LaTeX、PDF、ePub、Texinfo、man和纯文本等。

简介

时间轴

用户

以下一些使用Sphinx工具的网站：

了解更多 >> 使用Sphinx的项目

安装

使用pip安装

Sphinx软件包发布在PyPI上，可以使用pip安装：

pip install -U sphinx

使用docker安装

Sphinx的官方docker镜像有两个：

sphinxdoc/sphinx，常用的Sphinx镜像。
sphinxdoc/sphinx-latexpdf，比较大，主要使用LaTeX构建PDF的Sphinx镜像。

先安装好docker，使用以下命令来创建Sphinx项目：

docker run -it --rm -v /path/to/document:/docs sphinxdoc/sphinx sphinx-quickstart

Linux

Debian/Ubuntu下安装python3-sphinx使用apt-get：

apt-get install python3-sphinx

RHEL, CentOS下安装python3-sphinx使用yum：

yum install python-sphinx

使用源代码安装

使用git从Github下载源代码，然后pip安装

$ git clone https://github.com/sphinx-doc/sphinx
$ cd sphinx
$ pip install .

了解更多 >> Sphinx文档：安装

入门

了解更多 >> Sphinx文档-快速开始

文档结构

文档根目录下：

source 目录：存放用reStructuredText格式编写文档。
conf.py 文件：Sphinx 配置文件。可以设置网页模板主题，启用某些插件，配置路径等。

可以通过脚本sphinx-quickstart来快速生成。创建一个文档目录，在终端进入该目录，然后运行下面命令：

sphinx-quickstart

运行完后在文档目录下自动生成：

source 目录：存放用reStructuredText格式编写文档。
conf.py 文件：Sphinx 配置文件。
index.rst 文件：文档主页。
make.bat 文件：生成静态网页。
Makefile 文件：

编写内容

Sphinx支持大部分标准reStructuredText语法，Sphinx还提供了一些特定的语法。

生成网页

当你添加了一些文件和内容，就可以生成网页了使用sphinx-build程序，如：

sphinx-build -b html sourcedir builddir

如果你使用sphinx-quickstart快速生成的，可以直接使用make.bat来生成网页：

make html

现在静态网页可以在_build目录下的html目录中，直接打开浏览即可。

Autodoc

使用python语言的项目编写文档时候，可以使用插件autodoc来自动提取源代码中的文档。在conf.py中输入如下内容以开启autodoc：

extensions = ['sphinx.ext.autodoc']

然后

HTML 主题

Sphinx支持通过主题（themes）改变HTML输出的外观。

了解更多 >> Sphinx文档：HTML 主题

使用主题

常见主题

主题	描述	网址
pydata-sphinx-theme	基于Bootstrap 4，使用该主题的一些文档： Pandas 文档 NumPy 文档 MegEngine 文档安装： 1. 使用pip安装主题 `pip install pydata-sphinx-theme` 2. 在conf.py中设置 `html_theme = "pydata_sphinx_theme"`	源代码：https://github.com/pydata/pydata-sphinx-theme 示例：https://pydata-sphinx-theme.readthedocs.io/en/latest/
sphinx-rtd-theme	Read the Docs Sphinx Theme 安装： 1. 使用pip安装主题 `pip install sphinx-rtd-theme` 2. 在conf.py中设置 `html_theme = "sphinx_rtd_theme"`	https://github.com/readthedocs/sphinx_rtd_theme

制作主题

了解更多 >> Sphinx文档：HTML 主题开发

资源

官网

文章

@@ 第73行： / 第73行： @@
 然后
+==HTML 主题==
+Sphinx支持通过主题（themes）改变HTML输出的外观。
+{{了解更多
+|[https://www.sphinx-doc.org/zh_CN/master/usage/theming.html Sphinx文档：HTML 主题]
+}}
+===使用主题===
+===常见主题===
+{| class="wikitable"  style="width: 100%;
+! 主题
+! 描述
+! 网址
+|-
+| pydata-sphinx-theme
+| 基于[[Bootstrap]] 4，使用该主题的一些文档： <br \>[https://pandas.pydata.org/docs/ Pandas 文档]  <br \>[https://numpy.org/devdocs/ NumPy 文档]  <br \>[https://megengine.org.cn/doc/stable/zh/ MegEngine 文档]  <br \><br \>安装：<br \>1. 使用pip安装主题 <code>pip install pydata-sphinx-theme</code> <br \>2. 在conf.py中设置 <code>html_theme = "pydata_sphinx_theme"</code>
+| 源代码：https://github.com/pydata/pydata-sphinx-theme  <br \>示例：https://pydata-sphinx-theme.readthedocs.io/en/latest/
+|-
+|sphinx-rtd-theme
+|Read the Docs Sphinx Theme <br \><br \>安装：<br \>1. 使用pip安装主题 <code>pip install sphinx-rtd-theme</code> <br \>2. 在conf.py中设置 <code>html_theme = "sphinx_rtd_theme"</code>
+| https://github.com/readthedocs/sphinx_rtd_theme
+|-
+|
+|
+|
+|}
+===制作主题===
+{{了解更多
+|[https://www.sphinx-doc.org/zh_CN/master/development/theming.html Sphinx文档：HTML 主题开发]
+}}
 ==资源==
@@ 第82行： / 第113行： @@
 *[https://github.com/sphinx-doc/sphinx Sphinx 的 GitHub]
-===相关网站===
+===文章===
+*[https://zh.wikipedia.org/wiki/Sphinx_(文档生成器) 维基百科：Sphinx (文档生成器)]
 *[https://www.ibm.com/developerworks/cn/opensource/os-sphinx-documentation/ IBM Developer：Alfredo Deza-使用 sphinx 制作简洁而又美观的文档]
-*[https://www.biaodianfu.com/sphinx-documentation.html 标点符：使用Sphinx制作说明文档]
+*[https://www.neteye-blog.com/2021/04/how-to-create-a-custom-sphinx-theme/ NetEye: How to Create a Custom Sphinx Theme]
+*[https://www.neteye-blog.com/2021/04/advanced-sphinx-theme-customization/ NetEye: Advanced Sphinx Theme Customization]
-==参考文献==
-*[https://zh.wikipedia.org/wiki/Sphinx_(文档生成器) 维基百科：Sphinx (文档生成器)]
 [[分类:编程工具]]