使用sphinx生成美观的文档

原创 2015年07月06日 21:00:32

先上效果图


详情

首先,需要知道什么是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主题的官方文档



版权声明:本文为博主原创文章,未经博主允许不得转载。

相关文章推荐

使用Sphinx为你的python模块自动生成文档

Sphinx是一个可以用于Python的自动文档生成工具,可以自动的把docstring转换为文档,并支持多种输出格式包括html,latex,pdf等。安装 pip install sphinx...
  • preyta
  • preyta
  • 2017年06月23日 15:04
  • 1568

用sphinx_doc编写API文档

用sphinx_doc 编写API文档

Sphinx-doc编写文档

sphinx-doc是一种基于python的文档编写工具。python的官方帮助文档就是使用它编写的。sphinx-doc是reStructuredText,即使用带有简单语法的文本文件来编写文件,然...

sphinx自动化文档

sphinx自动化文档sphinx是python的御用自动化文档模块,通过提取代码中的文档注释(docstring)来生成代码文档,还是很方便的,你看到很多python官方教程,其实都是sphinx生...

Python文档生成工具pydoc

在Python中有很多很好的工具来生成字符串文档(docstring),比如说: epydoc、doxygen、sphinx,但始终觉得pydoc还是不错的工具,用法非常简单,功能也算不错,本文主要介...

用sphinx_doc编写API文档

用sphinx_doc 编写API文档

利用Sphinx轻松生成python代码的文档

大名鼎鼎的Numpy,Scipy等python扩展库都是使用Sphinx来自动生成文档的,就连Python的官方帮助文档也是使用Sphinx来发布的,由此可见Sphinx的流行和实用. 对Python...
  • rumswell
  • rumswell
  • 2013年11月02日 21:26
  • 11741

使用 sphinx 制作简洁而又美观的文档

Sphinx 是一种工具,它允许开发人员以纯文本格式编写文档,以便采用满足不同需求的格式轻松生成输出。这在使用 Version Control System 追踪变更时非常有用。纯文本文档对不同系统之...

使用sphinx快速生成Python API 文档

不管是开源还是闭源,文档都是很重要的。当然理论上说,最好的文档就是代码本身,但是要让所有人都能读懂你的代码这太难了。所以我们要写文档。大部分情况,我们不希望维护一份代码再加上一份文档,这样做很容易造成...

python自动生成易于阅读的html文档——使用Sphinx

Sphinx是一组可以用来从文本树生成一个HTML结构的脚本和docutils扩展。这个工具可以用来创建python文档,现在很多项目都使用它来制作文档。使用它内建的功能,生成一个真正精细的浏览系统,...
内容举报
返回顶部
收藏助手
不良信息举报
您举报文章:使用sphinx生成美观的文档
举报原因:
原因补充:

(最多只允许输入30个字)