Document python (1)

這邊介紹的是符合python2.6之後文件建議的格式以及使用的Sphinx專有的一些額外的設定.

Paragraphs

Paragraphs用句號結束並使用blank line來分隔paragraph.

List and Quotes

Sphinx並沒有增加什麼新的設定,列舉簡單例子.

* This is a bulleted list.
* It has two items, the second
 item uses two lines.

1. This is a numbered list.
2. It has two items too.

#. This is a numbered list.
#. It has two items too.

Sphinx在List部份沒有增加新的功能,可是刪減了字母list.

A. First item
B. Second item

(上面在sphinx是行不通的)

巢狀list在sphinx中也有一點改變, 每個level間要使用blank line分開,請見下例.

* this is
* a list

 * with a nested list
 * and some subitems

* and here the parent list continues

Definition list沒有特別的改變.

term (up to a line of text)
  Definition of the term, which must be indented

  and can even consist of multiple paragraphs

next term
  Description.

Source Code

Sphinx 通常使用 Literal code block 來描述 source code.

Literal code block 沒有變化一樣是由"::"定義下一個block表示Literal code block.

This is a normal text paragraph. The next paragraph is a code sample::

   It is not processed in any way, except
   that the indentation is removed.

   It can span multiple lines.

This is a normal text paragraph again.

Hyperlinks

使用 ''Link text <http://target>_'' 指示 Sphinx 建立連結,假如連結要顯示的文字 就是連結本身,那不必做特殊處理,sphinx會找出http link和mail並進行處理.

Directives

.. function:: foo(x)
          foo(y, z)
  :bar: no

  Return a line of text input from the user.

上例中 function 是 directive name. 代有兩個參數 foo(x) 和 foo(y, z), directive 後面要接一個blank line 作為分隔.

Footnotes

[#]_ 代表footnote, 請劍下例.

Lorem ipsum [#]_ dolor sit amet ... [#]_

.. rubric:: Footnotes

.. [#] Text of the first footnote.
.. [#] Text of the second footnote.

Note

也可以使用明確的數字代替井號.