sphinx自动化文档

sphinx自动化文档

sphinx是python的御用自动化文档模块，通过提取代码中的文档注释（docstring）来生成代码文档，还是很方便的，你看到很多python官方教程，其实都是sphinx生成的，比如数据分析的pandas:http://pandas.pydata.org/pandas-docs/stable/
废话不多说，下面开始。
需要注意的是，我使用的python3.5，sphinx1.4.

安装sphinx和sphinx_bootstrap_theme主题

安装方法可以使用pip方法安装，也可以先将源码包下载后使用setup安装。个人觉得sphinx_bootstrap_theme比sphinx中包含的几个主题要好看一些。
sphinx的官网地址:http://www.sphinx-doc.org/en/1.4.8/
sphinx_bootstrap_theme主题地址:http://ryan-roemer.github.io/sphinx-bootstrap-theme/

建立sphinx项目

在代码目录下安装shift+鼠标右键，打开cmd窗口，我的目录地址是 E:\pycharm
然后依次输入如下命令，注意，如果没有输入直接回车，则是使用默认选型

E:\pycharm> sphinx-quickstart
> Root path for the documentation [.]: doc  # 在当前目录下新建doc文件夹存放sphinx相关信息
> Separate source and build directories (y/n) [n]:   # 默认，直接回车
> Name prefix for templates and static dir [_]: 
> Project name: python123   # 输入项目名称
> Author name(s): 123   # 作者
> Project version: 1.0  # 项目版本
> Project release [1.0]:
> Project language [en]:   # 默认，回车
> Source file suffix [.rst]: 
> Name of your master document (without suffix) [index]:
> Do you want to use the epub builder (y/n) [n]:
> autodoc: automatically insert docstrings from modules (y/n) [n]: y  # 这个很重要，输入y
> doctest: automatically test code snippets in doctest blocks (y/n) [n]:
> int