使用sphinx生成美观的文档

jopen 9年前

先上效果图


详情

首先,需要知道什么是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