Sphinx

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

简介

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

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

pip install -U sphinx

Sphinx的官方docker镜像有两个：

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

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

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-quickstart来快速生成。创建一个文档目录，在终端进入该目录，然后运行下面命令：

sphinx-quickstart

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

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

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

sphinx-build -b html sourcedir builddir

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

make html

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

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

extensions = ['sphinx.ext.autodoc']

然后

Sphinx支持通过主题（themes）改变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