Sphinx autodoc with Django 1.4

Question

I'm having issues building the module autodocs for a Django 1.4.1 project. make html seems to be failing to read my docstrings because it's running into trouble importing my settings. All of the online guides I've seen suggest using

import settings
from django.core.management import setup_environ
setup_environ(settings)

but this is deprecated in 1.4, and the settings.configure() method doesn't seem appropriate. I haven't found nearly as much information for how to make things work in 1.4. I tried setting DJANGO_SETTINGS, but no luck. Any suggestions?

Answer 1

The problem seems to be that I incorrectly set a DJANGO_SETTINGS environment variable, when I needed to set DJANGO_SETTINGS_MODULE.

So, to be clear, because this info is not particularly well documented, there are two equivalent ways to setting up autodocs with Django 1.4+:

1. Set environment variables before running make html:

   export PYTHONPATH=<path to root of source>
   export DJANGO_SETTINGS_MODULE=myproject.settings
   

2. Do the equivalent in conf.py:

   sys.path.append('<path to root of source>')
   os.environ['DJANGO_SETTINGS_MODULE'] = 'myproject.settings'
   

I prefer the latter because I can set it in the configuration and the docs will build in any deployment.