Sphinx 的高級用法

Sphinx 的高級用法:
    1,Sphinx 的配置文件 conf.py, 在這里你可以配置Sphinx各個方面，使Sphinx按照你的要求讀取源文件並創建文檔.
    2,Sphinx 主要功能是使用 reStructuredText, 把許多文件組織成一份結構合理的文檔.
一，在index.html增加索引目錄
    index.rst 同級目錄下的 .rst 結尾文件 去掉文件后綴名
    maxdepth 表示最大二級目錄

.. toctree::
   :maxdepth: 2
   :caption: Contents:

   exmple
   exmple1
   exmple2
   exmple3

二，為'.py'文件自動生成 html 文檔
    在 conf.py 文件之中配置,相對於 當前 conf.py 文件的 '.py'文件

   import os
   import sys 
   sys.path.insert(0, os.path.abspath('..'))

在指定要顯示的 .rst 文件之中， run.py 就是要生成文檔的'.py'文件

.. automodule:: run
   :members:

三,為生成的文檔配置主題

    # Sphinx 提供三個主題 默認主題 alabaster
    # 安裝 sphinx_rtd_theme 主題
    # pip install sphinx_rtd_theme

    # 在 conf.py 之中更改主題
    html_theme = 'sphinx_rtd_theme'

四, 增加 logo 圖片 自帶了一個logo 位置

    # 在 conf.py 之中指定 logo 圖片 ,相對於 conf.py 的文件路徑
    html_logo = './_static/logo.jpg'

五, 函數在文檔之中展示
    1, 一般只需要使用 '::' 就可以(不加函數說明), 或者'::' 前面加上文字表明 函數說明
    2, 也可以使用 code-block 增加 其他功能 比如語法高亮
    3, 定義與 函數之間是像段落的關系 注意加上空格

::

    def say():
        print('hello world!')

source code again

Can add extra features when use code-block

.. code-block::
    :linenos:
    :emphasize-lines: 3,6

    is_directory()
       {
          DIR_NAME=$1
          if [ ! -d $DIR_NAME ]; then
             return 1
          else
             return 0
          fi
       }

六,引用和腳注
    1,在語句之中 使用 '[文字]_' 可以使用 '..[文字]' 為文字添加修飾 
    2, #f1 以 # 開頭顯示的是數字 數字實現自動增長

It is methioned by [Ref]_ that python is good.

.. [Ref] 《talk is good》

orem ipsum [#f1]_  dolor sit amet ... [#f2]_

Footnotes

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

七,替換
    1,在正文中使用'|文字|'這樣標簽，然后可以設定使用其他文本或者圖片來代替'文字'這個占位符

I like eat |apple| very much.

.. |apple| replace:: orange

八, 生成類的文檔:
    1, 可以按照以下格式定義 你可以緊挨着也可以 另起一行對齊
    2, ' py:decorator:: ' 指的是裝飾器 另起一行 對一個類之中的裝飾器進行說明

.. py:class:: Foo(object):
   .. py:method:: quux()
   .. py:attribute:: name
   .. py:staticmethod:: name(signature)
   .. py:classmethod:: name(signature)

.. py:decorator:: removename

   Remove name of the decorated function.

.. py:decorator:: setnewname(name)

   Set name of the decorated function to *name*.

 

九,通常將有用的命令或者代碼 進行陰影化

Code emphasis ::

   # ls -l
   # find . -perm -7 -print | xargs chmod o-w
   # ls -l

項目具體使用參考 githup

# 以上代碼存放位置
https://github.com/shiqilouyang/sphinx_doc

# 一個項目文檔參考
https://github.com/me115/linuxtools_rst