python sphinx 文檔自動生成方法

 

## sphinx 生成開發文檔
#### 配置
 1. 運行如下命令，即可生成 conf.py index.rst  Makefile 三個文件：
    
    `sphinx-quickstart`
 2. conf.py 負責全局配置：
    1. 注意一定要啟用 `autodoc`
    2. `autodoc` 對應配置在：
    
        `extensions = ['sphinx.ext.autodoc',
        'sphinx.ext.todo',
        'sphinx.ext.viewcode']
        `
    3. 配置 path 以供sphinx 在 `autodoc` 時能夠 `import` 對應的 module
 
        `sys.path.insert(0, os.path.abspath('.'))`
 
 3. index.rst 負責首頁的布局， 需要聲明 `autodoc`的位置，以及對應的 module
    1. 在module的__init__.py文件中聲明好 __all__
    2. 在 index.rst 中加入如下配置，注意空格格式
         
            .. automodule:: data_engineer.bark_engine
               :members:
               :undoc-members:
               :show-inheritance:
 4. 設置主題：ReadTheDocs
     1. 安裝:
         
            pip install sphinx_rtd_theme
                  
     2. 配置conf.py：
            
            import sphinx_rtd_theme
            html_theme = "sphinx_rtd_theme"
            html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]
            
 
#### 執行
    - sphinx-build -b html .  _build
#### 參考：
    1. 生成配置文件：sphinx-quickstart
    2. 配置source 掃描：https://www.ctolib.com/topics-46641.html
    3. 設置主題： https://segmentfault.com/a/1190000007233355