Can't generate autodoc using Sphinx in my Django project

Question

I'm addind documentation to my Django project (github link, the project is open source) using sphinx, but I'm getting a lot of bugs when a try to generate autodoc of python files. I'm including a models.py file with docstrings but, when a run make html I'm getting different bugs. I have made some changes and the bug is changing, but I'm not sure if I am fixing them or only generating a new bug. If a remove the inclusion of the models.py file, all run perfectly. In other words, the bug is only generated when I include the following lines in a .rst file:

.. automodule:: account.models
    :members:

Let me show you what have I done.

1. My first bug was the following, when I run the make html command:

WARNING: autodoc: failed to import module u'account.models'; the following exception was raised: No module named account.models

I have added the following lines to the sphinx confg.py file:

import os
import sys
sys.path.insert(0, os.path.abspath('../../'))

I have created a folder called docs to include all files generated by the sphinx-quickstart command, for this reason, the value of the abspath is ../../.

2. Ok, now, when I run the make html command, I got the second error:

ImproperlyConfigured: Requested setting USE_I18N, but settings are not configured. You must either define the environment variable DJANGO_SETTINGS_MODULE or call settings.configure() before accessing settings.

I have integrated the internazionalitation Django module to enable multiple languages in the application, I'm not sure how it is affecting the docs generation, but, to fix this bug, I have added the following lines to the sphinx conf.py file:

from django.conf import settings
settings.configure()

3. Now, if I run the make html command, I have the following message:

"The translation infrastructure cannot be initialized before the " AppRegistryNotReady: The translation infrastructure cannot be initialized before the apps registry is ready. Check that you don't make non-lazy gettext calls at import time.

To "fix it" (I'm not sure if it really has fixed it), I have the following lines to the sphinx conf.py file:

import django
django.setup()

4. But now, I'm getting the following message when I run the make html command:

RuntimeError: Model class django.contrib.contenttypes.models.ContentType doesn't declare an explicit app_label and isn't in an application in INSTALLED_APPS.

And now I can't find some option to fix it. If I remove the inclusion of the .py files from my .rst files, all run perfectly, but I need to include the docstrings created in all my python files.

How can I fix it?

Thank you so much.

Important links:

My project settings: settings.py

Sphinx folder: docs/

Note: I have added locally the following lines to the conf.py files:

from django.conf import settings
settings.configure()

import django
django.setup()

These changes are no visible in the github repository.

Answer 1

You need to tell Django which settings to use. Try this in docs/conf.py:

import os
import sys

# I've simplified this a little to use append instead of insert.
sys.path.append(os.path.abspath('../../'))

# Specify settings module
os.environ.setdefault('DJANGO_SETTINGS_MODULE', 'app.settings')

# Setup Django
import django
django.setup()

# ... leave the rest of conf.py unchanged

That should allow the rest of the build to run correctly.