Intersphinx links to Django’s documentation¶

Tags: django, python, book

Intersphinx is a very neat way to point at other projects’ documentation from within your own. Handy if you want to reference a Python module or an official Django setting or class.

You have to do some setup work, like enabling the intersphinx extension. Most of the time, your automatically generated sphinx configuration will already have it enabled out of the box. Now you need pointers at the other projects’ documentation (there needs to be a special objects.inv file with link target definitions). At the end of your file, add something like this:

intersphinx_mapping = {
    'python': ('http://python.readthedocs.org/en/v2.7.2/', None),
    'django': ('http://django.readthedocs.org/en/latest/', None),
    'sphinx': ('http://sphinx.readthedocs.org/en/latest/', None),
    }

Now you can do fun stuff like this:

Django knows about your URL configuration because you told it
where to find it with the :django:setting:`ROOT_URLCONF` setting.

Only… I got an error:

ERROR: Unknown interpreted text role "django:setting".

What? I couldn’t figure it out and asked a question on stackoverflow. I got some tips, but couldn’t get it to work.

Then I got an idea. Sphinx has a lot of things build in, but not Django’s custom Sphinx roles like setting! That’s not a standard Sphinx one. Perhaps you need to copy/paste the other project’s custom sphinx extensions to get it to work? Not terriby elegant, but worth a shot.

In the end I got it working by copying a small snippet from Django’s sphinx extension as _ext/djangodocs.py next to my documentation:

def setup(app):
    app.add_crossref_type(
        directivename = "setting",
        rolename = "setting",
        indextemplate = "pair: %s; setting",
    )

And I added the following to my Sphinx’ conf.py:

import os
import sys

...

sys.path.append(
    os.path.abspath(os.path.join(os.path.dirname(__file__), "_ext")))
# ^^^ I'll do that neater later on.

extensions = ['djangodocs',
              # ^^^ I added that one.
              'sphinx.ext.autodoc',
              ...
              ]

...

And… Yes, it worked!

So: intersphinx works, but if you point at a custom role, you need to have that custom role defined locally.