使用sphinx自动建立API文档（二）定制化

1、网站主题修改

上面生成的网页风格比较像flask的主页，实际上使用就是同一主题alabaster。
修改conf.py文件：html_theme = 'alabaster'。
将值修改为喜欢的风格，sphinxdoc的风格是matplotlib的主题样式；nature是pandas的主题，
个人比较喜欢nature，将上面修改为：

html_theme = 'nature'

重新运行

sphinx-apidoc -o ./source ../src/
make clean
make html

生成文档：

image.png

2、函数分页

上面运行完后，会发现，class Demo1、Demo1_ch 都在一页中，如下：

image.png

这样会有一些问题存在，当函数较多的时候，一页中会很长，难以看清（如老版 matplotlib 的 API 页面）。
这里需要用到一个扩展：automodapi
（主页：https://sphinx-automodapi.readthedocs.io/en/latest/automodapi.html#module-sphinx_automodapi.automodapi）
使用pip安装后。
修改conf.py，添加sphinx_automodapi.automodapi：

image.png

将source下.rst文件中的automodule均替换为automodapi：
如demo2.rst：

demo2 module
============
.. automodule:: demo2
    :members:
    :undoc-members:
    :show-inheritance:

改为

demo2 module
============
.. automodapi:: demo2
    :members:
    :undoc-members:
    :show-inheritance:

如果嫌麻烦，可以写一个自动替换的脚本replace_api.py：

import os
source_api_path = 'source'
automo_method = 'automodapi' # automodapi | automodsumm | automodule
for rst_file in os.listdir(source_api_path):
    if rst_file.endswith('.rst'):
        with open(source_api_path + os.sep + rst_file, 'r') as f:
            contents = f.read()
        contents = contents.replace('automodule', automo_method)
        with open(source_api_path + os.sep + rst_file, 'w') as f:
            f.write(contents)

将replace_api.py放于doc目录下，运行替换。重新运行建立 html 文件。