码迷,mamicode.com
首页 > 编程语言 > 详细

python文档生成工具:pydoc、sphinx;django如何使用sphinx?

时间:2019-02-14 19:01:40      阅读:239      评论:0      收藏:0      [点我收藏+]

标签:case   efi   start   tom   cep   __init__   fail   tin   文件结构   

 

 

 

如何将Sphinx生成的html文档集成进入Django:

https://www.cnblogs.com/flowjacky/p/6251177.html

 

使用sphinx-quickstart只会生成index.dst,需哟啊使用api

make html会提示错误,根据提示进行修改

 

以下内容来自:http://www.huangwenchao.com.cn/2015/12/djangp-sphinx.html

安装 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”这一点,并不是那么容易达到的,我就碰到了这个问题:

Stackoverflow: Sphinx-apidoc on django build html failure on django.core.exceptions.AppRegistryNotReady

最终发现了需要在外部装载 django 上下文的方法,参见:

https://docs.djangoproject.com/en/1.9/topics/settings/#calling-django-setup-is-required-for-standalone-django-usage

也就是说,在这里的解决办法是:

编辑 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 的异常了。

 

 

参考:

1、http://www.huangwenchao.com.cn/2015/12/djangp-sphinx.html

python文档生成工具:pydoc、sphinx;django如何使用sphinx?

标签:case   efi   start   tom   cep   __init__   fail   tin   文件结构   

原文地址:https://www.cnblogs.com/shengulong/p/10376437.html

(0)
(0)
   
举报
评论 一句话评论(0
登录后才能评论!
© 2014 mamicode.com 版权所有  联系我们:gaon5@hotmail.com
迷上了代码!