sphinx 编写文档使用记录

Posted 2020-11-27 oloroso

目录

• 1、安装 sphinx 环境
• 2、生成 Sphinx 工程
  • 配置主题和插件
• 3、编写并构建文档

1、安装 sphinx 环境

首先安装 python 环境

这里可以安装 anacond ，使用起来比较方便。参考：Anaconda的安装和详细介绍（带图文）

我这里直接使用 scoop 来安装。

# 安装 miniconda 
scoop install -g miniconda3

Installing ‘miniconda3‘ (4.7.12.1) [64bit]
Miniconda3-4.7.12.1-Windows-x86_64.exe (51.5 MB) [============================================================] 100%
Checking hash of Miniconda3-4.7.12.1-Windows-x86_64.exe ... ok.
Running installer... done.
Linking C:scoopappsminiconda3current => C:scoopappsminiconda34.7.12.1
Creating shim for ‘python‘.
Creating shim for ‘pythonw‘.
Creating shim for ‘python3‘.
Persisting envs
‘miniconda3‘ (4.7.12.1) was installed successfully!

然后安装 Sphinx 软件

打开 anaconda3 自带的 Anaconda Prompt ，输入下面命令进行安装

# 安装 Sphinx 本身，这里也可以使用 pip 安装
conda install Sphinx
# 安装 sphinxcontrib-fulltoc 插件
#  Sphinx 默认是不产生侧边栏的Tree 结构的，所以需要插件sphinxcontrib-fulltoc 
pip install sphinxcontrib-fulltoc

2、生成 Sphinx 工程

创建一个项目目录，然后进入目录，执行 sphinx-quickstart 命令。

这里会依次询问选项：

• 分离源码和编译目录（y/n）
• 工程名称：可以写中文
• 作者名称：可以写中文
• 工程发行版：写一个版本号就是。 Sphinx有一个“版本”和“发行版”的概念。每个版本可以有多个发行版本。例如，对于Python，版本类似于2.5或3.0，而发行版类似于2.5.1或3.0a1。如果不需要这种双重结构，只需将两者设置为相同的值。
• 工程语言：zh_cn 是中文

sphinx-quickstart
Welcome to the Sphinx 2.4.4 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: helpdoc
> Author name(s): solym
> Project release []: 1.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

Creating file .sourceconf.py.
Creating file .sourceindex.rst.
Creating file .Makefile.
Creating file .make.bat.

Finished: An initial directory structure has been created.

You should now populate your master file .sourceindex.rst and create other documentation
source files. Use the Makefile to build the docs, like so:
   make builder
where "builder" is one of the supported builders, e.g. html, latex or linkcheck.

配置主题和插件

Sphinx 生成的项目文件结构中，配置文件 conf.py 本身也是一个 python 脚本，所以进行修改的时候要注意符合 python 语法。

• 配置主题：

  打开当前工程目录下的 source/conf.py 文件，找到 html_theme = ‘alabaster‘ 这一行，将主题名称（alabaster）修改为你喜欢的即可（当前可选：classic、sphinxdoc、scrolls、agogo、traditional、nature、haiku、pyramid、bizstyle）。

  具体有哪些主题可以选择，可以查看官网文档 Sphinx home|Documentation ? HTML theming support。

• 配置插件：

  打开当前工程目录下的 source/conf.py 文件，找到extensions = []，在数组内（中括号内）添加需要的插件即可。比如说前面安装的 ‘sphinxcontrib.fulltoc‘ 就可以添加到里面。

  更多插件相关资料，可以查看官网文档 Sphinx home|Documentation ? Extensions。

  插件	简述
  sphinx.ext.autosectionlabel	允许使用标题的参考章节
  sphinx.ext.mathjax sphinx.ext.jsmath sphinx.ext.imgmath	Sphinx对HTML输出的数学公式支持 mathjax / jsmath：通过 java script 渲染 imgmath：渲染为图片

3、编写并构建文档

具体的编写方式，可以参考：Sphinx 使用手册 、reStructuredText入门 。

编写完成文档之后，可以使用 make 脚本来生成目标格式文件，例如要生成 html 就执行 make html 即可，生成的目标文件在 build 目录下。

make
Sphinx v2.4.4
Please use `make target‘ where target is one of
  html        to make standalone HTML files
  dirhtml     to make HTML files named index.html in directories
  singlehtml  to make a single large HTML file
  pickle      to make pickle files
  json        to make JSON files
  htmlhelp    to make HTML files and an HTML help project
  qthelp      to make HTML files and a qthelp project
  devhelp     to make HTML files and a Devhelp project
  epub        to make an epub
  latex       to make LaTeX files, you can set PAPER=a4 or PAPER=letter
  text        to make text files
  man         to make manual pages
  texinfo     to make Texinfo files
  gettext     to make PO message catalogs
  changes     to make an overview of all changed/added/deprecated items
  xml         to make Docutils-native XML files
  pseudoxml   to make pseudoxml-XML files for display purposes
  linkcheck   to check all external links for integrity
  doctest     to run all doctests embedded in the documentation (if enabled)
  coverage    to run coverage check of the documentation (if enabled)