使用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主題的官方文檔。