使用sphinx生成美观的文档

先上效果图

详情

首先，需要知道什么是restructuredtext，可以理解为类似于markdown的一个东西。

然后

1. 安装，pip install sphinx
2. 进入存放文档的目录， 在命令行， sphinx-quickstart，根据需要一路回车，会生成一堆东西，包括conf.py和make等
3. 根据需要修改conf.py
4. 编写rst文件，比如默认的index.rst或链接的rst文件。
5. 在命令行，make html

上图的效果，是使用了一个主题叫sphinx_bootstrap_theme。(PS.有很多主题可以选择)

conf.py中关于这个主题的配置是加了下面几行代码

import sphinx_bootstrap_theme
html_theme = 'bootstrap'
html_theme_path = sphinx_bootstrap_theme.get_html_theme_path()
html_theme_options = {
    'navbar_title': "Sandglass",
    'globaltoc_depth': 2,
    'globaltoc_includehidden': "true",
    'navbar_class': "navbar navbar-inverse",
    'navbar_fixed_top': "true",
    'bootswatch_theme': "united",
    'bootstrap_version': "3",
}

生成的文档的文件夹布局

图中的index.rst文件

Welcome to sandglass's documentation!
=====================================

安装
------------

  pip install sandglass


概览
--------

**sandglass(沙漏)** 是一个增强的、友好的时间处理库，目的是为了解放程序员的生产力。
在python中有太多处理时间的库，datetime/date/time/calendar等等。需要记的细节太多，选择困难。
而sandglass就是解决这个的青霉素。从各种麻烦的转换中解脱出来。
只需记住 **Sandglass对象** 和 **ben()** 、 **tslice()** 、 **cronwalk()** 这几个主要的api即可。

特性
----------
 + api简洁，开箱即用
 + 增强接管datetime
 + (此次略去xx字)

快速上手
---------
在sandglass中，核心对象是 **Sandglass对象** 。通过这个对象，可以方便的获取各个时间属性和操作::
    
    #获取属性
    >>>sg = ben('2013,1,1 13:14:15')
    >>>sg.year,sg.month,sg.day,sg.hour,sg.minute,sg.second,sg.microsecond
    (2013, 1, 1, 13, 14, 15, 0)
    (此次略去xx字)

API文档
-----------------

.. toctree::
   :maxdepth: 2

   api

Todo
---------
* Add timezone support

Changelog
---------
**0.0.1**

* Initial release

Indices and tables
==================

* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`

更多详情请看sphinx的官方文档。

以及sphinx-bootstrap-theme 主题的官方文档。

原文：http://blog.csdn.net/handsomekang/article/details/46778895