[Fixed]-How to build sphinx documentation for django project

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)

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:

1. I used a relative path (two directories up), but you can go ahead and put an absolute path if you’d like
2. My project name is dataentry and the settings.py file is inside that folder; change the name (dataentry) to your project name

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.

Late but using Django>=1.9 and sphinx>=1.6.4 set the path equivalent to the project BASE_DIR in the 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. 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. 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):

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()