用 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的格式

1. table (a table with title)

2. csv-table (a table generated from comma-separated values)
3. 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文件。

也欢迎关注我的个人微信公众号：正午不早了
也可以访问我的技术博客