Daniel Roy Greenfeld

Daniel Roy Greenfeld

About | Articles | Books | Jobs | News | Tags

Configuring Sphinx Auto-Doc with projects having Django dependencies

How to make it so projects with Django as a dependency benefit from Sphinx's auto-documentation features.

The Problem

I want to be able to document open source packages with Sphinx (ex. xocto) and have Sphinx automatically document the Django helpers. This isn't quite the same as documenting a Django project, so I wasn't sure if the otherwise awesome sphinxcontrib-django would be the right tool. Fortunately, there's a solution that doesn't require any additional packages.

The Solution


First, in the Sphinx docs folder, create a file called django_settings.py and add the following:

Minimal file so Sphinx can work with Django for autodocumenting.

Location: /docs/django_settings.py

# INSTALLED_APPS with these apps is necessary for Sphinx to build
# without warnings & errors
# Depending on your package, the list of apps may be different

Next, at the top of Sphinx's conf.py, add the following:

# docs/conf.py
import os
import sys

import django

# Note: You may need to change the path to match
# your project's structure
sys.path.insert(0, os.path.abspath(".."))  # For discovery of Python modules
sys.path.insert(0, os.path.abspath("."))  # For finding the django_settings.py file

# This tells Django where to find the settings file
os.environ["DJANGO_SETTINGS_MODULE"] = "django_settings"
# This activates Django and makes it possible for Sphinx to
# autodoc your project


In one of your documentation files, perhaps docs/localtime.rst:

.. automodule:: xocto.localtime

Or if you are using myst-parser to use Markdown with Sphinx. In this case, the file would be at docs/localtime.md:

.. automodule:: xocto.localtime

Come and work with me

My employer is hiring! We've got dozens of roles and hundreds of positions open across multiple fields in several countries (USA, UK, Germany, France, Australia, Japan, Italy, Spain, and more). Our mission is to address climate change through decarbonization, electrification, and being good citizens. We're a growing group of companies with a big mission, and we're looking for people who want to make a difference. Check out our careers page to see if what we do excites you and our open roles page to discover if there's a role that you find interesting.

Tags: octopus kraken python django howto