Sphinx¶
1 安装¶
pip install sphinx：执行成功会安装 sphinx-apidoc、sphinx-autogen、sphinx-build、sphinx-quickstart 四个工具
2 sphinx-quickstart¶
- https://www.sphinx-doc.org/en/master/man/sphinx-quickstart.html sphinx-quickstart 是一个交互式工具，它询问有关项目的一些问题，然后生成一个完整的文档目录和示例 Makefile，用于 sphinx-build。
2.1 交互式方式¶
此中方式只需要执行 sphinx-quickstart，然后根据提示，选择，填入项目名、作者、版本、语言等信息。
2.2 非交互方式¶
此方式提前把需要的信心以参数的形式传入 sphinx-quickstart 中, 如：
[shw@rocky test2]$ sphinx-quickstart -q -p test2 -a shw -v 0 --sep
Finished: An initial directory structure has been created.
You should now populate your master file /home/shw/code/sphinx/test2/source/index.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.
需要指定 -q 选项，说明不需要交互，然后还必须指定 -p, -a, -v 选项。
以下一些常用选项：
optional arguments:
-h, --help show this help message and exit
-q, --quiet quiet mode
--version show program's version number and exit
Structure options:
--sep if specified, separate source and build dirs
--no-sep if specified, create build dir under source dir
--dot DOT replacement for dot in _templates etc.
Project basic options:
-p PROJECT, --project PROJECT
project name
-a AUTHOR, --author AUTHOR
author names
-v VERSION version of project
-r RELEASE, --release RELEASE
release of project
-l LANGUAGE, --language LANGUAGE
3 sphinx-build¶
- https://www.sphinx-doc.org/en/master/man/sphinx-build.html
- 语法：
sphinx-build [OPTIONS] SOURCEDIR OUTPUTDIR [FILENAMES...]sphinx build 查找配置设置的<sourcedir>/conf.py。 - 示例：
sphinx-build ./ build-dir，第一个参数表示源目录是当前目录，第二个参数表示生成位置所在目录是 build-dir
usage: sphinx-build [OPTIONS] SOURCEDIR OUTPUTDIR [FILENAMES...]
Generate documentation from source files. sphinx-build generates documentation from the files in SOURCEDIR and places it in OUTPUTDIR. It looks for 'conf.py' in SOURCEDIR for the
configuration settings. The 'sphinx-quickstart' tool may be used to generate template files, including 'conf.py' sphinx-build can create documentation in different formats. A format is
selected by specifying the builder name on the command line; it defaults to HTML. Builders can also perform other tasks related to documentation processing. By default, everything that is
outdated is built. Output only for selected files can be built by specifying individual filenames.
positional arguments:
sourcedir path to documentation source files
outputdir path to output directory
filenames a list of specific files to rebuild. Ignored if -a is specified
optional arguments:
-h, --help show this help message and exit
--version show program's version number and exit
general options:
-b BUILDER builder to use (default: html)
-a write all files (default: only write new and changed files)
-E don't use a saved environment, always read all files
-d PATH path for the cached environment and doctree files (default: OUTPUTDIR/.doctrees)
-j N build in parallel with N processes where possible (special value "auto" will set N to cpu-count)
build configuration options:
-c PATH path where configuration file (conf.py) is located (default: same as SOURCEDIR)
-C use no config file at all, only -D options
-D setting=value override a setting in configuration file
-A name=value pass a value into HTML templates
-t TAG define tag: include "only" blocks with TAG
-n nit-picky mode, warn about all missing references
console output options:
-v increase verbosity (can be repeated)
-q no output on stdout, just warnings on stderr
-Q no output at all, not even warnings
--color do emit colored output (default: auto-detect)
1. -N, --no-color do not emit colored output (default: auto-detect)
-w FILE write warnings (and errors) to given file
-W turn warnings into errors
--keep-going with -W, keep going when getting warnings
-T show full traceback on exception
-P run Pdb on exception
For more information, visit <https://www.sphinx-doc.org/>.
3.1 -b buildername 指定构建目标类型（过时）¶
Sphinx 能构建以下类型的文件，不指定，则默认输出 html 格式文件。
1. html : to make standalone HTML files
2. dirhtml : to make HTML files named index.html in directories
3. singlehtml : to make a single large HTML file
4. pickle : to make pickle files
5. json : to make JSON files
6. htmlhelp : to make HTML files and an HTML help project
7. qthelp : to make HTML files and a qthelp project
8. devhelp : to make HTML files and a Devhelp project
9. epub : to make an epub
10. latex : to make LaTeX files, you can set PAPER=a4 or PAPER=letter
11. latexpdf : to make LaTeX and PDF files (default pdflatex)
12. latexpdfja : to make LaTeX files and run them through platex/dvipdfmx
13. text : to make text files
14. man : to make manual pages
15. texinfo : to make Texinfo files
16. info : to make Texinfo files and run them through makeinfo
17. gettext : to make PO message catalogs
18. changes : to make an overview of all changed/added/deprecated items
19. xml : to make Docutils-native XML files
20. pseudoxml : to make pseudoxml-XML files for display purposes
3.2 -M buildername¶
用于取代-b 选项的，相比较-b 选项，会首先创建一个构建类别目录，然后构建生成的目标文件会放在此目录。