参考如下:
1. http://www.huangwenchao.com.cn/2015/12/djangp-sphinx.html
2. https://www.jianshu.com/p/d4a1347f467b
3. https://www.cnblogs.com/flowjacky/p/6251177.html
简单配置如下 ( Django)
1. 安装sphinx
2. 为你的代码写标准的docstring文档
3. 开始初始化我们的文档，在项目根目录下运行 （我打算放到根目录下的static文件夹）
4. 根据提示一步步来，我只处理下以下几项，其它的都是默认回车
> Project name: TEST
> Author name(s): X.F
> Project language [en]: zh_cn
> autodoc: automatically insert docstrings from modules (y/n) [n]: y
> viewcode: include links to the source code of documented Python objects (y/n) [n]: y
5. 修改 static/sphinx_doc/source/conf.py
# import os
# import sys
# sys.path.insert(0, os.path.abspath('.'))
import os
import sys
sys.path.insert(0, os.path.abspath('./../../..'))
import django # 这个最好可以加载顶部和其他的 import 放在一起
# 下面将 settings 加到环境变量里面，等一下启动的时候就会是用这个配置
os.environ['DJANGO_SETTINGS_MODULE'] = 'myproject.settings'
# 关键，用这句加载模块和上下文
django.setup()
6. 生成代码文档，到项目根目录下
sphinx-apidoc -o static/sphinx_doc/source/ .
Creating file static/sphinx_doc/source/manage.rst.
Creating file static/sphinx_doc/source/quickstart.rst.
Creating file static/sphinx_doc/source/quickstart.migrations.rst.
Creating file static/sphinx_doc/source/snippets.rst.
Creating file static/sphinx_doc/source/snippets.migrations.rst.
Creating file static/sphinx_doc/source/tutorial.rst.
Creating file static/sphinx_doc/source/modules.rst.
7. 进入static/sphinx_doc/source ，修改index.rst文件，让其可以加载modules.rst内容
.. toctree:: :maxdepth: 2 :caption: Contents: modules
8. 回退到sphinx_doc目录，运行 make html 生成
9. 将文档集成进django，可以通过url访问
url.py 中添加
from django.views.static import serve
from django.conf import settings
urlpatterns = [
url(r'^sphinx_docs/(?P<path>.*)$', serve, {'document_root': settings.SPHINX_DOCS_ROOT}),
url(r'^sphinx_docs/', serve, {'document_root': settings.SPHINX_DOCS_ROOT, 'path': 'index.html'}),
....
]
settings.py 中添加配置项
SPHINX_DOCS_ROOT = os.path.join(STATIC_ROOT, 'sphinx_doc', 'build', 'html')
10. 为文档更新一个友好的主题
然后再次修改 static/sphinx_doc/source/conf.py
#html_theme = 'alabaster'
import sphinx_rtd_theme
html_theme = "sphinx_rtd_theme"
html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]
最后再重新运行一次 make html即可生效
11. 运行runserver , localhost:8000/sphinx_docs/index.html 看看吧