sphinx安装及简单使用

如果你要编写技术文档, 可以用 reStructuredText 或 Markdown 格式编辑文件，然后使用 Sphinx 工具转换成 html, PDF, ePub等格式，或者托管到 github 并导入 readthedocs 网站。

1. 安装软件包（需要先安装 Python）

   pip install sphinx sphinx_intl sphinx_rtd_theme recommonmark
   

   sphinx: 文档生成工具
   sphinx_intl: 多语言工具
   recommonmark: sphinx支持markdown的插件
   sphinx_rtd_theme: sphinx的readthedocs主题插件

2. 创建存放文档的目录，执行 sphinx-quickstart 命令

   cd /path/to/project
   mkdir docs
   cd docs
   sphinx-quickstart
   

   sphinx-quickstart 会创建基本配置。一般情况下，你只要接受默认值就行了。当上述命令执行完后，在 docs目录下，你会找以 index.rst和 conf.py。 你可以编辑这两个文件，加入一些项目信息。

   Makefile : 批处理指令，使用 make 命令时，用来构建文档输出。
   _build : 用于存放最终生成的文档。
   _static : 所有不属于文档源代码的文件（如图像）均存放于此处，构建时会它们链接在一起。
   conf.py : 一个 Python 文件，存放 Sphinx 的配置值，包括执行 sphinx-quickstart 时选中的那些值。
   index.rst : 文档项目的 root 目录。如果将文档有多个文件，该目录会连接这些文件。

3. 修改conf.py，加入 Markdown 支持

   extensions = ['recommonmark']
   

4. 修改 conf.py，使用 sphinx_rtd_theme 风格。修改

   html_theme = 'alabaster'
   

   为

   import sphinx_rtd_theme
   html_theme = "sphinx_rtd_theme"
   html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]
   

5. 执行命令，生成输出

   make html
   

   输出的html文件在 docs\_build\html目录下， 打开 index.html即可。