学习sphinx制作文档
摘要
本篇中的sphinx不是开发搜索功能的软件，而是生成文档的工具。它使用reStructuredText编写文档，这是一种类似Markdown的简单标记语言。
比Markdown强大之处在于，它支持使用代码编写数学公式，使用代码制作流程图等图片，最后由sphinx解析成各种文件，比如HTML、PDF等。
所以，Markdown适合于单篇无体系的文章，而Sphinx更适合用于写作具有紧密联系的一些列文章，比如读书笔记、书稿等。
windows下使用sphinx
安装
安装 python
下载 python，下载地址：Windows x86-64 web-based installer
各版本解释
x86 适合 32 位操作系统，x86-64适合64位操作系统。
web-based installer 是需要通过联网完成安装的。我的理解是，下载的是一部分，全部安装包是
在启动此 installer 后，通过网络获取的。
executable installer 是可执行文件(*.exe)方式安装。下载下来的就是全部安装包。
embeddable zip file 嵌入式版本，可以集成到其它应用中。不理解。
下载安装包之后，直接双击安装。
安装 sphinx
打开CMD，执行命令
pip install Sphinx
CMD 窗口出现错误信息：
PermissionError: [WinError 5] 拒绝访问。: 'c:\\program files\\python35\\Lib\\site-packages\\pytz'
You are using pip version 8.1.1, however version 8.1.2 is available.
You should consider upgrading via the 'python -m pip install --upgrade pip' command.
执行命令
python -m pip install --upgrade pip
仍然出现同样的错误。难道是用户权限问题。切换到管理员用户执行命令
python -m pip install --upgrade pip
屏幕打印信息
C:\WINDOWS\system32>python -m pip install --upgrade pip
Collecting pip
Using cached pip-8.1.2-py2.py3-none-any.whl
Installing collected packages: pip
Found existing installation: pip 8.1.1
Uninstalling pip-8.1.1:
Successfully uninstalled pip-8.1.1
Successfully installed pip-8.1.2
成功更新了pip。再回到普通用户执行安装 Sphinx 的命令
pip install Sphinx
屏幕打印信息的最后一部分
File "c:\program files\python35\lib\site-packages\pip\utils\__init__.py", line 83, in ensure_dir
os.makedirs(path)
File "c:\program files\python35\lib\os.py", line 241, in makedirs
mkdir(name, mode)
PermissionError: [WinError 5] 拒绝访问。: 'c:\\program files\\python35\\Lib\\site-packages\\colorama'
仍然是权限问题。在管理员CMD下再执行安装Sphinx命令
pip install Sphinx
屏幕打印信息最后一部分
Running setup.py install for MarkupSafe ... done
Successfully installed Jinja2-2.8 MarkupSafe-0.23 Pygments-2.1.3 Sphinx-1.4.6
alabaster-0.7.9 babel-2.3.4 colorama-0.3.7 docutils-0.12 imagesize-0.7.1 pytz-2016.6.1
six-1.10.0 snowballstemmer-1.2.1
安装sphinx成功了。
设置 the documentation sources
执行命令
sphinx-quickstart
运行结果如下图
根据需要回答它的一系列问题，对于 “autodoc” extension，一定要回答 y。
关于语言的回答，英文选择 en，简体中文选择 zh_CN， 繁体中文选择 zh_TW。
最后的运行结果是这样的
Creating file H:/sphinx\source\conf.py.
Creating file H:/sphinx\source\index.rst.
Creating file H:/sphinx\Makefile.
Creating file H:/sphinx\make.bat.
Finished: An initial directory structure has been created.
You should now populate your master file H:/sphinx\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.
定义文档结构--Defining document structure
编译文档 - Running the build
执行命令
sphinx-build -b html sourcedir builddir
这条命令不能直接执行，需根据自己的需要修改。
-b，选择需要的编译器，即要编译成什么格式的文件。
sourcedir，要编译的源文件路径。必须设置。
builddir，编译后的文件输出的路径。必须设置。
执行命令
sphinx-build -b html H:/sphinx/source H:/sphinx/build
执行成功后，以前为空的 H:/sphinx/build 目录下面出现了很多文件。
.
├── Makefile
├── build
├── source
└── make.bat
- Makefile：它是一个包含指令的文件，在使用 make 命令时，可以使用这些指令来构建文档输出。
- build：这是触发特定输出后用来存放所生成的文件的目录。
- source：源代码目录。
- make.bat：使用
make html可以取代sphinx-build -b html。
