djangopython-sphinx

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


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.


Solution

  • Update: @vdboor's answer points at https://pypi.org/project/sphinxcontrib-django/ , which is the modern solution.


    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.