前言
首先,由于 Sphinx 文档系统的先进性和优越性,我们如果做一个 Django 项目都不用,简直太浪费了!
所以,我们可以在 django 的文件夹里面创建一个文档文件夹,然后将文档内容在里面建设。
于是,我们起码可以得到两种功德:
- 我们可以简单地将各种逻辑描述整合到一个仓库里面,然后使用优美的 reStructureText 生成文档。这样的文档做出来,自己看或者给客户看,不能不说是一种享受。
- 除了自己敲的注释,我们还可以自动生成 django 代码里面的 doc string 来生成文档,这样的话,我们就要优化我们的注释规范,提高代码质量的同时,花费极少的额外工作来获得一套优质的文档。
对于在这里面如何用 reStructureText 友好的方式编写 Python 注释,可以参考这篇 PEP-287:
https://www.python.org/dev/peps/pep-0287/
安装 Sphinx 并且生成文档项目
首先我们假设已经有了一个 django 项目的架构:
myproject/
myproject/
__init__.py
settings.py
urls.py
wsgi.py
myapp/
migrations/
__init__.py
admin.py
models.py
tests.py
views.py
在这个基础上,我们要在里面加一个 docs 文件夹放文档项目:
pip3 install Sphinx
mkdir docs
cd docs
sphinx-quickstart
# 注意 autodoc 的地方一定要选是,其他选默认没什么问题。
# ...
# 最后直接生成一下:
make html
如上,先安装 Sphinx 库,然后创建一个目录,在里面执行 sphinx-quickstart,填写参数之后就可以产生文档项目的内容。
这个时候,我们应该获得一个这样的目录:
myproject/
myproject/
myapp/
docs/
_build/
doctrees/
html/
_static/
_templates/
conf.py
index.rst
Makefile
很好,我们现在通过 myproject/docs/_build/html/
就已经获得一个生成好的文档静态网站了,将这个目录静态部署,就已经搭好基本的文档项目了。
撰写基本的手工文档
具体的 reStructuredText 语法,在这里就不多说了,本人其实将这篇文档翻译了一遍,不过还是自行参考原文吧:
然后,我们只需要在项目文档里面创建文件结构以及 *.rst
文档源文件,进行编辑即可。
比较关键的就是在文档中搭建目录引用关系,最终这些目录树会将所有文档的章节拼接成一个整体的目录树:
例如我们在 docs/index.rst
里面加入这个目录树定义:
.. toctree::
:maxdepth: 3
usecases/index
myapp/models
myapp/admin
myapp/views
这样的话,对应会目录到下面路径的这几个文件:
myproject/
docs/
usecases/
index.rst
myapp/
admin.rst
models.rst
views.rst
注意,在我们计划中,usecases
用来存放纯手写的用例文档,而 myapp
文件夹里面的内容是要打算在代码中直接抽取的。
如何实现这一点?自动抽取代码呢?
绑定 Django 项目并从项目生成代码
首先,我们需要让文档项目的上下文能正确加载 django,就好像我们调用 python manage.py shell
得到的上下文一样。
然后,我们在文档里面就可以通过这样的 reST 指令块来指定抽取,以 myapp.model.rst
为例:
myapp.models module
===================
.. automodule:: myapp.models
:members:
:undoc-members:
:show-inheritance:
只要指定了这个 ..automodule
指令,再 make 就可以实现抽取。
但是,我们前面的这个前提“需要让文档项目的上下文能正确加载 django”这一点,并不是那么容易达到的,我就碰到了这个问题:
最终发现了需要在外部装载 django 上下文的方法,参见:
也就是说,在这里的解决办法是:
编辑 myproject/docs/conf.py
,找到:
# sys.path.insert(0, os.path.abspath('.'))
附近这段,然后编辑成这几行:
import django # 这个最好可以加载顶部和其他的 import 放在一起
# 这个注意由于 django 根目录位于 `docs/conf.py` 本身的上一级目录,因此要用父目录
sys.path.insert(0, os.path.abspath('..'))
# 下面将 settings 加到环境变量里面,等一下启动的时候就会是用这个配置
os.environ['DJANGO_SETTINGS_MODULE'] = 'myproject.settings'
# 关键,用这句加载模块和上下文
django.setup()
有了这一套,就不会出现 django.core.exceptions.AppRegistryNotReady
的异常了。
从今以后,写文档就是一件令人愉悦的事情,祝各位文档愉快!
【转载请附】愿以此功德,回向 >>
原文链接:http://www.huangwenchao.com.cn/2015/12/djangp-sphinx.html【使用 Sphinx 创建 Django 整体项目文档】