标签：case efi start tom cep __init__ fail tin 文件结构
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
首先我们假设已经有了一个 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，就好像我们调用 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 的异常了。
参考：
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
