用 Sphinx 写文档
本文记录使用Sphinx 写文档，以及利用Nginx 完成部署的整个过程。
环境
Sphinx 本身是使用Python 写的，所以你需要Python 的环境。由于我在Ubuntu14.04 下自然不用操心这个问题，如果是在Windows 环境下我没试过。
- 安装Sphinx
pip install Sphinx
- 扩展安装
Sphinx 有个很强大扩展能力，官网给出了很多. 实在不满意还可以自己定制 除非是对外文档，我想不需要这么炫的功能。有基本的完全满足需求。
Sphinx 默认是不产生侧边栏的Tree 结构的，所以找了个插件sphinxcontrib-fulltoc
pip install sphinxcontrib-fulltoc
在里文档项目路径下运行下面的命令，我的在test-doc 目录下。
StartProject
sphinx-quickstart
过程中会有一些提示，需要填写项目名称，和选择一些基础的设置，我的选择方式是大部分默认，当选择yes or no 的时候基本都是yes
完了之后会在当前路径下产生一些文件，之所以是在当前路径下，是以为我上面选择的是当前路径，仔细看上图。
.
├── build
├── make.bat
├── Makefile
└── source
├── conf.py
├── index.rst
├── _static
└── _templates
配置
扩展
source 路径是存放文档原文件的地方，conf.py是配置文件，能设置主题，扩展等。
现在就把插件添加进去，打开conf.py 添加最后一项，其他的都是在上面选择的时候产生的，我基本选择的是yes ,所以会比较多
extensions = [
33 'sphinx.ext.autodoc',
34 'sphinx.ext.doctest',
35 'sphinx.ext.intersphinx',
36 'sphinx.ext.todo',
37 'sphinx.ext.coverage',
38 'sphinx.ext.mathjax',
39 'sphinx.ext.ifconfig',
40 'sphinx.ext.viewcode',
41 'sphinx.ext.githubpages',
42 'sphinxcontrib.fulltoc',
43 ]
主题
Sphinx 提供很多主题，去官网选择，你会发现很多主题都是很熟悉，如果你用Python 的化。默认是使用Flask一样的主题
打开conf.py 下面的位置可以编辑主题
html_theme = 'alabaster'
语法
Sphinx 的文档默认是.rst文件，语法和Markdown 类似，但是我感觉某些地方会比较有优势
找了一下有个清晰的语法文档，有意思的是也是用Sphinx 写的。
官网也有，但是感觉这个会比较好，可能是颜色的问题。
新建一个example.rst 然后在index.rst 里按如下添加
title
title 的书写有几种和Html 中H标签对应
H1 -- Top of Page Header
************************
There should only be one of these per page and this will also -- when
converting to pdf -- be used for the chapters.
H2 -- Page Sections
===================
H3 -- Subsection
----------------
H4 -- Subsubsection
+++++++++++++++++++
table
我觉得优势就在Talbe 的写法上，Sphinx 支持三种table的格式
- table (a table with title)
- csv-table (a table generated from comma-separated values)
- list-table (a table generated from a list of lists)
我觉得list-talbe 会比Markdown 的书写方式好，Markdown 的写法，很难让那些竖线对齐，当文字很长没有规则的时候写的时候就会很乱
list-talbe 没有这个问题，官网给出的一个例子
.. list-table:: Frozen Delights!
:widths: 15 10 30
:header-rows: 1
* - Treat
- Quantity
- Description
* - Albatross
- 2.99
- On a stick!
* - Crunchy Frog
- 1.49
- If we took the bones out, it wouldn't be
crunchy, now would it?
* - Gannet Ripple
- 1.99
- On a stick!
当然会有其他功能，可以添加图片之类的，链接......
部署
我是产生Html 静态文件然后用Nginx 代理这个目录。
在根目录下运行下面的命令，就可以在build 路径下产生html 文件，
make html
然后打开index.html
效果如下
把Html和所有静态文件推到服务器上，配置Nginx 然后就可以访问了
Nginx 配置方法见Nginx官网
如果你事件下来 发现得不到预期的结果，通常是你哪里有问题,比如书写的时候缩进没对齐，多了空格之类都会导致结果不正确。
Sphinx 还可以直接产生PDF文件。
也欢迎关注我的个人微信公众号：正午不早了
也可以访问我的技术博客
