How to build sphinx documentation for django project
Solution 1
The migration features introduced in Django 1.7 prevents the previous answers from working on newer versions. 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. Add this to your Sphinx project's conf.py:
os.environ['DJANGO_SETTINGS_MODULE'] = 'projectname.settings'
import django
django.setup()
Solution 2
Add the following to your conf.py and you will not need to set DJANGO_SETTINGS_MODULE each time:
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)
Solution 3
With Django 1.6, I couldn't use the answer by @MikeRyan since from django.core.management import setup_environ
has been deprecated. Instead, I went to my conf.py file and added the following:
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:
- I used a relative path (two directories up), but you can go ahead and put an absolute path if you'd like
- My project name is
dataentry
and the settings.py file is inside that folder; change the name (dataentry) to your project name
Solution 4
I think you have to make Sphinx aware of the DJANGO_SETTINGS_MODULE environment variable. 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.
Related videos on Youtube
miki725
Updated on June 04, 2022Comments
-
miki725 about 2 years
I have a django project, which I document using reST in docstrings to do the following:
- Help diagloags within IDE
- Later on to build HTML documentation using Sphinx
My documentation shows up properly within IDE (PyCharm), however I can't configure Sphinx to generate HTML documentation for me.
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. Thank you.
EDIT
My project name is saassapp and the module I am trying to make a doc for is called studyview.
- Sphinx
conf.py
file: http://pastebin.com/HTYdc1rR - Sphinx
index
file: http://pastebin.com/bu1r38TQ - Result of
make html
: http://pastebin.com/MWJj94EE
-
mzjn over 12 yearsHave you run the spinx-quickstart script? It sets up the Sphinx environment for you.
-
Simon Bergot over 12 yearsYou can use the subprocess module
-
Dave over 11 yearsis it better to do the sys.path in absolute terms or in relative terms?
-
Mike Ryan over 11 yearsUsing a relative path will make it more reusable.
-
jooks over 11 yearsThanks, the sys.path.append line with an absolute path saved me a big headache.
-
Subhamoy S. about 10 yearsWith the mentioned directory structure, I cannot see how you could call the Django project like a module from the sphinx conf file.
-
miki725 about 10 yearsthanx for the update. Ill change to accept your answer to keep things up-to-date.
-
Raffi about 8 yearsThis works well, except if the
automodule
directive contains eg.:undoc-members:
. In that case, Sphinx extracts the documentation from the parent classes and misses some of them (for instancemodels.FileField
). This works well if:undoc-members:
is removed and the class attributes are properly documented. -
Joab Mendes over 7 yearsI keep getting a
ImportError: No module named 'projectname'
when I try amake html
. Do you know what it might be? -
Simon over 7 years@JoabMendes: Unless you explicitly named your Django project
projectname
you have to adjust that to whatever you named your project module. In other words,DJANGO_SETTING_MODULE
should hold a valid python path pointing to your project's settings module. -
Joab Mendes over 7 years@Simon it holds the projectname, I just used it as example haha. I specified the
DJANGO_SETTINGS_MODULE
but I'm using a separate settings architecture. Inside the main project folder I have a settings folder withbase
,local
andproduction
settings files. Both, local and production import base. So myDJANGO_SETTINGS_MODULE
is something likeprojectname.settings.local
. Do you think I need a specific configuration in this case? (I have tried to edit the sys.path) Also, I cannot import any module directly in conf.py (My tree: pastebin.com/y0HqZ8pz) -
Simon over 7 years@JoabMendes Oh sorry, I thought that was literally the error message you got. I think it should work as long as you specify a complete Django settings file, regardless of where it's located. But as you can't import any other modules either I would first look into python path and/or virtualenv setup to make sure you can import the settings module in a python REPL.
-
Joab Mendes over 7 years@Simon I made a work around importing every module I wanted to autodoc directly in conf.py with their full paths (In this way for python 3.4: stackoverflow.com/questions/67631/…). The only problem, as I said, is that I have to import manually all the modules. Well, thank you anyway for your attention. (:
-
Shadi over 6 years
setup_environ
seems to be deprecated