学习sphinx制作文档、编写书稿

学习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

运行结果如下图

学习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 

1. Makefile：它是一个包含指令的文件，在使用 make 命令时，可以使用这些指令来构建文档输出。
2. build：这是触发特定输出后用来存放所生成的文件的目录。
3. source：源代码目录。
4. make.bat：使用 make html 可以取代 sphinx-build -b html。

参考资料

First steps with Sphinx

sphinx安装和基本操作

使用 sphinx 制作简洁而又美观的文档