一.以下均在mac環境下，Linux系統中的操作：

1. 配置Python環境   

$ python --version

Python 2.7.6

sudo easy_install sphinx

error: Download error for https://pypi.python.org/packages/source/s/sphinx_rtd_theme/sphinx_rtd_theme-0.1.9.tar.gz#md5=86a25c8d47147c872e42dc84cc66f97b: _ssl.c:492: The handshake operation timed out

所以我特意聲明瞭安裝的版本

sudo easy_install-2.7 Sphinx

如果還安裝不成功，那麼先安裝macPorts 

http://www.macports.org/install.php

然後參照這個網頁進行安裝

http://www.sphinx-doc.org/en/stable/install.html#mac-os-x-install-sphinx-using-macports

二.基本配置

2.1切換到你的共做目錄下：執行命令：

sphinx-quickstart

Welcome to the Sphinx 1.3.3 quickstart utility.

Please enter values for the following settings (just press Enter to

accept a default value, if one is given in brackets).

Enter the root path for documentation.

> Root path for the documentation [.]: MyAPI

You have two options for placing the build directory for Sphinx output.

Either, you use a directory "_build" within the root path, or you separate

"source" and "build" directories within the root path.

> Separate source and build directories (y/n) [n]: y

Inside the root directory, two more directories will be created; "_templates"

for custom HTML templates and "_static" for custom stylesheets and other static

files. You can enter another prefix (such as ".") to replace the underscore.

> Name prefix for templates and static dir [_]: API

The project name will occur in several places in the built documentation.

> Project name: MerchantAPI

> Author name(s): lidan

Sphinx has the notion of a "version" and a "release" for the

software. Each version can have multiple releases. For example, for

Python the version is something like 2.5 or 3.0, while the release is

something like 2.5.1 or 3.0a1.  If you don't need this dual structure,

just set both to the same value.

> Project version: 3.0

> Project release [3.0]: 3.0.0

If the documents are to be written in a language other than English,

you can select a language here by its language code. Sphinx will then

translate text that it generates into that language.

For a list of supported codes, see

http://sphinx-doc.org/config.html#confval-language.

> Project language [en]: 

The file name suffix for source files. Commonly, this is either ".txt"

or ".rst".  Only files with this suffix are considered documents.

> Source file suffix [.rst]: 

One document is special in that it is considered the top node of the

"contents tree", that is, it is the root of the hierarchical structure

of the documents. Normally, this is "index", but if your "index"

document is a custom template, you can also set this to another filename.

> Name of your master document (without suffix) [index]: index

Sphinx can also add configuration for epub output:

> Do you want to use the epub builder (y/n) [n]: n

Please indicate if you want to use one of the following Sphinx extensions:

> autodoc: automatically insert docstrings from modules (y/n) [n]: y

> doctest: automatically test code snippets in doctest blocks (y/n) [n]: y

> intersphinx: link between Sphinx documentation of different projects (y/n) [n]:n

> todo: write "todo" entries that can be shown or hidden on build (y/n) [n]: n

> coverage: checks for documentation coverage (y/n) [n]: n

> pngmath: include math, rendered as PNG images (y/n) [n]: n

> mathjax: include math, rendered in the browser by MathJax (y/n) [n]: n

> ifconfig: conditional inclusion of content based on config values (y/n) [n]: n

> viewcode: include links to the source code of documented Python objects (y/n) [n]:n

A Makefile and a Windows command file can be generated for you so that you

only have to run e.g. `make html' instead of invoking sphinx-build

directly.

> Create Makefile? (y/n) [y]: y

> Create Windows command file? (y/n) [y]: y

然後在這個目錄下就會自動生成一下幾個檔案，如圖：

2.2 終端切換到MyAPI  執行

 make html

│  make.bat                         # 編譯指令碼
│  Makefile                         # Linux下Makefile檔案
│
├─build         # make編譯後產生的網頁目錄在build/html目錄下
└─source                             # 文件原始碼目錄
    │  conf.py                      # 配置檔案
    │  index.rst                    # 文件原始檔入口
    ├─_static               # 編譯過程產生的一些圖片之類的    
    └─_templates                    # 模板

2.3 修改html的樣式：

在 conf.py中可以修改 sphinx的風格，還有文件名、作者等。一般使用過sphinx-quickstart建立一個工程後，以後新建工程，可以直接拷貝資料夾，只修改conf.py就行。這裡看下常用的風格，

#html_theme = ‘default’ 
#html_theme = ‘alabaster’ 
html_theme = ‘sphinxdoc’

】

更改完樣式以後要通過  make html命令才能生效

2.3 標題

上面，我們把每個章節單放在一個獨立的rst檔案中了，章節標題即一級標題，一級標題只要在標題名字下面加====就行了，=號的個數要超過標題的長度，否則會告警。幾類標題的符號依次如下，使用的方式與一級標題一樣：

一級標題： = 
二級標題： - 
三級標題： + 
四級標題： ^

一下是四種標題書寫格式以及對應的html樣式：

第一部分   （一級標題）
========================================================


第一章  （二級標題）
--------------------------------------------------
            二級標題的內容。。。。。

1.1.1 章節    （三級標題）
+++++++++++++++++++++++++++++++++++++++++++++++++

                 三級標題的內容（1.1.1）

1.1.1.1   節  （四級標題）
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

     四級標題內容



1.1.2 章節
++++++++++++++++++++++++++++++++++++

     章節的內容（1.1.2）

2.4 插入圖片：  

新建一個imsges目錄 ，將圖片放在此目錄下   ，此目錄與source目錄屬於同一級

在rst 中引用圖片格式

.. image:: ../images/1.jpg
   :width: 500
   :height: 500

設定寬高一定要空三個空格 ，通過設定寬高來控制圖片的尺寸

2.5  編寫API 的json資料   

格式以及對應的樣式如下：

.. code-block:: javascript

   {
     update_date_time:'2015-1-20'
    }

2.6  如果json資料過長處理

json資料所佔的篇幅比較大，那麼可以單獨寫一個js檔案，將json資料格式化以後放在js檔案中（假設此檔名為test.js）那麼在rst 檔案中引用這個js檔案的時候只要寫成：

.. literalinclude:: test.js
   :language: javascript

2.7 測試介面

測試介面一般會有引數的拼接，如果不採用一定格式，那麼引數中的雙引號複製下來貼上到網址的時候就會出現問題，不能請求到引數，

沒有設定格式的時候是這樣顯示的：

這樣的格式複製下來要手動修改每一個雙引號，非常麻煩，即使編譯的時候雙引號用的是英文格式下的，呈現在html上的也是像上面一樣的，正確的格式設定應該如下：

.. code-block:: html


   http://localhost:64984/ItemAdd?data={"orderID":7394,"addItems":[{"menuID":522,"count":2,"isPaid":false,"addPriceByRestaurant":0,"remark":"",priceOptions:[{"priceOptionID":19,"addPrice":1,"count":"2"}]}]}}

2.8  編輯一個層級的API

呈現在html上的結構如下：   這個介面分成兩個部分   order  和 message

點選order進去的介面：

選中其中一項檢視一個具體的介面：

大致結構如上，下面看怎麼完成order部分：每個檔案下除了必要的rst檔案，就是各個具體的介面，其中js檔案是json較長資料，供rst檔案直接引用，上面已經提到過，rst和js的編寫上面都說過了，此處就不在多說，重點是index檔案怎樣處理

這是order/index 中的格式。message中的結構也是一樣的。

source下的index（html 入口index）結構如下：兩個目錄結構分別指向它們的 index.rst檔案

 merchant  商戶端介面
==============================================


.. toctree::
   :maxdepth: 1

   order/index.rst

.. toctree::
   :maxdepth: 1

   message/index.rst

         每次有更改一定要用 make html 命令編譯一次，才會在html 生效   

         API入口的在build/html/index.html    檢視

終於搞定了

PS：找時間錄製一個使用的視訊吧

date: 2015-12-4  週五