标签：read 就是 table hat 文件 项目 XML splay paper
首先安装 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:\scoop\apps\miniconda3\current => C:\scoop\apps\miniconda3\4.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
创建一个项目目录，然后进入目录，执行 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 .\source\conf.py.
Creating file .\source\index.rst.
Creating file .\Makefile.
Creating file .\make.bat.
Finished: An initial directory structure has been created.
You should now populate your master file .\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.
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：渲染为图片 |
具体的编写方式，可以参考：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)
标签：read 就是 table hat 文件 项目 XML splay paper
原文地址：https://www.cnblogs.com/oloroso/p/12725922.html
