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