How to link with intersphinx to django-specific constructs (like settings)? - django

Question

With a proper intersphinx setup, you can link to Django classes from your own documentation like this:
:class:`django:django.db.models.Model`
But how do you link to a setting? Django uses its own :setting: construct for that instead of something build-in like :class:. How do I link to a setting with intersphinx?
I've tried various incantations, but none work (and some are probably plain wrong):
:ref:`django:ROOT_URLCONF`
:ref:`django:root_urlconf`
:setting:`django:ROOT_URLCONF`
:ref:`django:setting:ROOT_URLCONF`
:django:setting:`ROOT_URLCONF`
Errors like undefined label: django:root_urlconf and Unknown interpreted text role "setting" greet me.

Answer 1

The problem: my local sphinx did not know about Django's custom sphinx roles, like setting. So a perfectly fine intersphinx reference like this:
:django:setting:`ROOT_URLCONF`
does not work until you've told Sphinx about the intersphinx target's custom role.
In the end 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',
...
]
...
So: intersphinx works, but if you point at a custom role, you need to have that custom role defined locally.

Answer 2

You need to look at the objects.inv for django to figure out what the correct cross reference should be.
It appears that:
:std:setting:`ROOT_URLCONF <django:ROOT_URLCONF>`
should work.
Somehow I have the objects.inv for django but can't find the URL I retrieved it from, in theory it should be https://docs.djangoproject.com/en/1.4/objects.inv but that redirects several times eventually resulting in a file-not-found error.