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.

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 ../../.

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

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

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.

sphinx has a lot of configuration details that can get you. Where you run the command can affect the relative paths. If you're importing django in your sphinx script, perhaps you're not in the right folder when you run it? (I don't know django, so maybe it automates some of this?) — Marc Maxmeister
– Marc Maxmeister, Commented Jun 21, 2018 at 22:22

solarissmoke · Accepted Answer · 2018-06-22 04:13:57Z

15

+50

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.

edited Jun 22, 2018 at 4:13

answered Jun 22, 2018 at 4:07

solarissmoke

31.7k15 gold badges76 silver badges80 bronze badges

Sign up to request clarification or add additional context in comments.

1 Comment

Andrés Quiroga Over a year ago

You have the solution. Thank you so much.

Collectives™ on Stack Overflow

Can't generate autodoc using Sphinx in my Django project

1 Answer 1

1 Comment

Your Answer

Linked

Hot Network Questions

Collectives™ on Stack Overflow

1 Answer 1

1 Comment

Your Answer

Sign up or log in

Post as a guest

Linked

Related