如何利用sphinx自动生成文档

参考如下:

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 

写道

pip install Sphinx

2. 为你的代码写标准的docstring文档

3. 开始初始化我们的文档，在项目根目录下运行　（我打算放到根目录下的static文件夹）

写道

sphinx-quickstart static/sphinx_doc

 4. 根据提示一步步来，我只处理下以下几项，其它的都是默认回车

写道

> Separate source and build directories (y/n) [n]: y

> 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. 生成代码文档，到项目根目录下

写道

注意:-o 后面跟的是保存rst文件的路径， 你的index.rst在哪个目录，那你就指定哪个目录。然后在后面的是你的项目(代码)路径

sphinx-apidoc -o static/sphinx_doc/source/ .

我这里是用的. , 表示将整个项目都生成文档，你也可以自己指定app生成，如　./test_app

效果类似　　

写道

~/tutorial$ 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. 为文档更新一个友好的主题

写道

pip install sphinx_rtd_theme

    然后再次修改　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　看看吧