一捆蜀、普通文檔創(chuàng)建

pip install sphinx # 安裝依賴
sphinx-quickstart # 創(chuàng)建文檔向?qū)?
# 上一步將創(chuàng)建如下目錄
├─build # 編譯后的文件存放目錄
└─source  # 文檔源文件目錄
    ├─_static
    ├─_templates
    ├─conf.py # 文檔配置信息
    └─index.rst # 首頁(yè)，rst為reStructuredText簡(jiǎn)寫
└─make.bat
└─Makefile

先不用管太多轰传，運(yùn)行命令
sphinx-build -b html .\source .\build
或
make html
看一下生成的build下生成的文件驴党，tree \f ./build

├─doctrees
│      environment.pickle
│      index.doctree
│
└─html # 生成的最終文檔
    │  .buildinfo
    │  genindex.html
    │  index.html # 主文件
    │  objects.inv
    │  search.html
    │  searchindex.js
    │
    ├─_sources
    │      index.rst.txt
    │
    └─_static # 資源文件
            alabaster.css
            ...
            jquery.js
            ....
            minus.png
          

打開(kāi)html/index.html 就可以看到文檔。

解讀一下index.rst, #之后的為注釋获茬，這不是rst文件的語(yǔ)法港庄，只是為了說(shuō)明內(nèi)部含義

.. toctree::   # 文檔入口方法
   :maxdepth: 2  # 參數(shù)為maxdepth, 值為2
   :caption: Contents: # 同上也是參數(shù),綜合以上，可以理解為調(diào)用了方法 toctree(maxdepth=2,caption='Contents')
                 # 空一行锦茁，以下代碼不是自動(dòng)生成攘轩，是為了說(shuō)明語(yǔ)法而加入的。
    subdir1/subdir11 # 子目錄1码俩，其下須有 index.rst文件內(nèi)含 ..toctree:: 命令,subdir11同樣如此。 注意歼捏，這里由于maxdepth限定稿存，所以只能到subdir11，第三級(jí)目錄無(wú)法在該文件中添加
    subdir2 # 子目錄2瞳秽“曷模可見(jiàn)index.rst文件就是組織文檔結(jié)構(gòu)的文件，子目錄下保持這種結(jié)構(gòu)练俐，就可以完整的生成一個(gè)有層級(jí)的文檔袖迎。

Indices and tables # 生成python文檔時(shí)起作用
==================

* :ref:`genindex`  # * 表示li的記號(hào)，:ref:表示一個(gè)引用腺晾，genindex為 index:: 命令所產(chǎn)生的索引燕锥，見(jiàn)后面的代碼，
* :ref:`modindex`
* :ref:`search`

.. index:: # 僅僅作為顯示example悯蝉，并沒(méi)有對(duì)應(yīng)到module归形，真實(shí)例子，須參考下面的說(shuō)明
    single: 關(guān)鍵詞1; 關(guān)鍵詞2; 關(guān)鍵詞3;   # 
    pair: 蘋果; 香蕉
    triple: module; search; path

.. toctree::
rst格式參考
rst標(biāo)記語(yǔ)言官方參

二鼻由、python 文檔生成 參考

)
先創(chuàng)建兩個(gè)python文件
mkdir src && cd src && touch demo1.py && touche demo2.py

• demo1.py

class Demo1():
    """類的功能說(shuō)明"""

    def add(self,a,b):
        """兩個(gè)數(shù)字相加暇榴，并返回結(jié)果"""
        return a+b
    
    def rest_style(self,a,b):
        """
        This is a reST style.

        :param a: 加數(shù)
        :param b: 被加數(shù)
        :returns: a+b
        :raises keyError: raises an exception
        """
        return a+b


    def google_style(self, arg1, arg2):
        """函數(shù)功能.

        函數(shù)功能說(shuō)明.

        Args:
            arg1 (int): arg1的參數(shù)說(shuō)明
            arg2 (str): arg2的參數(shù)說(shuō)明

        Returns:
            bool: 返回值說(shuō)明

        """
        return True

    def numpy_style(self, arg1, arg2):
        """函數(shù)功能.

        函數(shù)功能說(shuō)明.

        Parameters
        ----------
        arg1 : int
            arg1的參數(shù)說(shuō)明
        arg2 : str
            arg2的參數(shù)說(shuō)明

        Returns
        -------
        bool
            返回值說(shuō)明

        """
        return True

• demo2.py

def my_function(a, b):
    """函數(shù)功能說(shuō)明 numpy style

     >>> my_function(2, 3)
     6
     >>> my_function('a', 3)
     'aaa'

    """
    return a * b

• 修改source/conf.py

# 文件首部，加入module 系統(tǒng)path蕉世，否則無(wú)法加載module
import os
import sys
sys.path.insert(0, os.path.abspath('../src'))

# 修改extension
extensions = ['sphinx.ext.autodoc',
    'sphinx.ext.doctest',
    'sphinx.ext.intersphinx',
    'sphinx.ext.todo',
    'sphinx.ext.coverage',
    'sphinx.ext.napoleon', # 兼容 google style和numpy style
    'sphinx.ext.mathjax']

• python文件轉(zhuǎn)為rst文件
  sphinx-apidoc -o ./source ./src/
  可以看到source文件夾下多了三個(gè)文件:demo1.rst,demo2.rst,module.rst