如何利用sphinx自动生成文档

  • Post author:
  • Post category:其他


参考如下:

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 看看吧



版权声明:本文为xiaolin01999原创文章,遵循 CC 4.0 BY-SA 版权协议,转载请附上原文出处链接和本声明。