[Fixed]-Sphinx and re-usable Django apps

by

11👍

✅

If you don’t want to make your documentation dependent on a “demo” project, then you can manually build the settings in your conf.py. In the path setup section:

import django
from django.conf import settings
import os
import sys

# add path to sys.path (this might be different in your project)
sys.path.insert(0, os.path.abspath('..'))

# pass settings into configure
settings.configure(
    INSTALLED_APPS = [
        'django.contrib.admin',
        'django.contrib.auth',
        'django.contrib.contenttypes',
        'django.contrib.sessions',
        'django.contrib.messages',
        'django.contrib.staticfiles',
        'my_reusable_app',
        'any_other_dependencies',
    ]
)

# call django.setup to load installed apps and other stuff
django.setup()

# ... continue with rest of conf.py

Now Sphinx can import the app modules without having a project settings.py. Other settings can be passed to settings.configure().

👤Greg Schmit

4👍

It’s not an answer to the question

What do I place within conf.py to properly load the application without there being a settings.py file ?

but an alternative approach: Put a minimal, viable Django project in the reusable package. It can be used for implementation examples, testing (including code coverage), development and doc generation. We do it that way in our company’s private repositories and I have seen a few django packages on github that do it too.

A typical structure of my packages looks like this:

docs
├── conf.py
├── ... rst files
mypackage          # the actual package
mypackage_demo     # the Django project
├── .coveragerc
├── manage.py
├── settings.py
README.rst
requirements.txt
setup.py

In docs/conf.py I check for a settings environment variable and use the demo project if non is given:

if not os.environ.get('DJANGO_SETTINGS_MODULE'):
    os.environ['DJANGO_SETTINGS_MODULE'] = 'mypackage_demo.settings'
django.setup()

That way you could build the docs using another project by setting the DJANGO_SETTINGS_MODULE environment variable before calling sphinx.

settings.py just contains the minimal configuration necessary to run the application. The absolute minimum for Django to work are these:

BASE_DIR = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
SECRET_KEY = ''
INSTALLED_APPS = [
    'mypackage'
]
👤masterfloda

1👍

I did have the same issue with Django 1.11 and Sphinx 1.5.5. I did not manage to get it working properly and all the solutions you mentioned above did not work either. In the end I solved it by adding this to my Sphinx conf.py:

import sys, os

project_path = os.path.abspath('.')
# For Django to know where to find stuff.
os.environ.setdefault("DJANGO_SETTINGS_MODULE", "my_project.settings")
sys.path.append(project_path)

# For settings.py to load.
os.chdir(project_path)

# For the models to load.
from django.core.wsgi import get_wsgi_application
application = get_wsgi_application()
👤Maxime Deuse

Leave a comment