[英]How to build sphinx documentation for django project
I have a django project, which I document using reST in docstrings to do the following: 我有一个django项目,我在docstrings中使用reST来记录以下内容:
My documentation shows up properly within IDE (PyCharm), however I can't configure Sphinx to generate HTML documentation for me. 我的文档在IDE(PyCharm)中正确显示,但我无法配置Sphinx为我生成HTML文档。
Here is the structure of my project 这是我的项目的结构
+--------------------------------------------+
| /saassapp # django project path |
| /docs # dir for sphinx |
| conf.py # sphinx config file |
| ... |
| settings.py # django settings |
| /studyview # django app |
| ...
| ... |
+--------------------------------------------+
Any ideas? 有任何想法吗? An examle of the conf.py file would be very useful.
对conf.py文件的检查非常有用。 Thank you.
谢谢。
EDIT 编辑
My project name is saassapp and the module I am trying to make a doc for is called studyview. 我的项目名称是saassapp,我试图制作文档的模块叫做studyview。
conf.py
file: http://pastebin.com/HTYdc1rR conf.py
文件: http : conf.py
index
file: http://pastebin.com/bu1r38TQ index
文件: http : //pastebin.com/bu1r38TQ make html
: http://pastebin.com/MWJj94EE make html
结果: http : //pastebin.com/MWJj94EE The migration features introduced in Django 1.7 prevents the previous answers from working on newer versions. Django 1.7中引入的迁移功能可以防止以前的答案适用于较新的版本。 Instead you will have to do a manual setup.
相反,您将不得不进行手动设置。 Analogous to all previous answers you'll first have to make sure Django can find your settings, and then call
django.setup()
which will load the settings and setup your models. 类似于之前的所有答案,您首先必须确保Django可以找到您的设置,然后调用
django.setup()
来加载设置并设置模型。 Add this to your Sphinx project's conf.py : 将此添加到您的Sphinx项目的conf.py中 :
os.environ['DJANGO_SETTINGS_MODULE'] = 'projectname.settings'
import django
django.setup()
Add the following to your conf.py and you will not need to set DJANGO_SETTINGS_MODULE each time: 将以下内容添加到conf.py中,每次都不需要设置DJANGO_SETTINGS_MODULE:
import sys, os
sys.path.append('/path/to/your/project') # The directory that contains settings.py
# Set up the Django settings/environment
from django.core.management import setup_environ
from myproject import settings
setup_environ(settings)
With Django 1.6, I couldn't use the answer by @MikeRyan since from django.core.management import setup_environ
has been deprecated. 使用Django 1.6,我无法使用@MikeRyan的答案,因为
from django.core.management import setup_environ
已被弃用。 Instead, I went to my conf.py file and added the following: 相反,我去了我的conf.py文件并添加了以下内容:
import sys
import os
sys.path.append(os.path.join(os.path.dirname(__file__), '..'))
os.environ['DJANGO_SETTINGS_MODULE'] = 'dataentry.settings'
from django.conf import settings
Let me explain each line: 让我解释一下:
dataentry
and the settings.py file is inside that folder; dataentry
, settings.py文件位于该文件夹中; change the name (dataentry) to your project name I think you have to make Sphinx aware of the DJANGO_SETTINGS_MODULE environment variable. 我认为你必须让Sphinx了解DJANGO_SETTINGS_MODULE环境变量。 So do
那样做
export DJANGO_SETTINGS_MODULE=mysite.settings
(or whatever is the right value for you) (或者对你来说什么是合适的价值)
Then execute 然后执行
make html
in the same terminal session. 在同一个终端会话中。
Late but using Django>=1.9
and sphinx>=1.6.4
set the path equivalent to the project BASE_DIR
in the conf.py
迟到但使用
Django>=1.9
和sphinx>=1.6.4
设置相当于conf.py
项目BASE_DIR
的conf.py
import django
sys.path.insert(0, os.path.dirname(os.path.dirname(os.path.dirname(__file__))))
os.environ["DJANGO_SETTINGS_MODULE"] = "project.settings"
django.setup()
You actually don't need a separate settings
module. 您实际上不需要单独的
settings
模块。 It's sometimes easier to have one (when tests and doc share settings) but not required. 有时更容易(当测试和文档共享设置时)但不是必需的。
This is how dj-stripe sets up django for sphinx . 这就是dj-stripe如何为狮身人面像设置django 。 The key here is the
settings.configure
call with INSTALLED_APPS
as it is the only one setting key required (if your app does not require more of course): 这里的关键是使用
INSTALLED_APPS
调用settings.configure
,因为它是唯一需要的一个设置键(如果你的应用程序当然不需要更多):
import django
from django.conf import settings
from django.utils.encoding import force_text
from django.utils.html import strip_tags
import djstripe # noqa
# If extensions (or modules to document with autodoc) are in another directory,
# add these directories to sys.path here. If the directory is relative to the
# documentation root, use os.path.abspath to make it absolute, like shown here.
# sys.path.insert(0, os.path.abspath('.'))
cwd = os.getcwd()
parent = os.path.dirname(cwd)
sys.path.append(parent)
settings.configure(
INSTALLED_APPS=[
"django.contrib.admin",
"django.contrib.auth",
"django.contrib.contenttypes",
"django.contrib.sessions",
"django.contrib.sites",
"jsonfield",
"djstripe",
],
SITE_ID=1,
STRIPE_PUBLIC_KEY=os.environ.get("STRIPE_PUBLIC_KEY", ""),
STRIPE_SECRET_KEY=os.environ.get("STRIPE_SECRET_KEY", ""),
)
django.setup()
声明:本站的技术帖子网页,遵循CC BY-SA 4.0协议,如果您需要转载,请注明本站网址或者原文地址。任何问题请咨询:yoyou2525@163.com.