Make django docs intersphinx work

docs/_ext/djangodocs.py

@@ -0,0 +1,81 @@
+# Taken from https://github.com/django/django/blob/master/docs/_ext/djangodocs.py
+
+import re
+from sphinx import addnodes
+
+
+# RE for option descriptions without a '--' prefix
+simple_option_desc_re = re.compile(
+        r'([-_a-zA-Z0-9]+)(\s*.*?)(?=,\s+(?:/|-|--)|$)')
+
+
+def setup(app):
+    app.add_crossref_type(
+        directivename="setting",
+        rolename="setting",
+        indextemplate="pair: %s; setting",
+    )
+    app.add_crossref_type(
+        directivename="templatetag",
+        rolename="ttag",
+        indextemplate="pair: %s; template tag"
+    )
+    app.add_crossref_type(
+        directivename="templatefilter",
+        rolename="tfilter",
+        indextemplate="pair: %s; template filter"
+    )
+    app.add_crossref_type(
+        directivename="fieldlookup",
+        rolename="lookup",
+        indextemplate="pair: %s; field lookup type",
+    )
+    app.add_description_unit(
+        directivename="django-admin",
+        rolename="djadmin",
+        indextemplate="pair: %s; django-admin command",
+        parse_node=parse_django_admin_node,
+    )
+    app.add_description_unit(
+        directivename="django-admin-option",
+        rolename="djadminopt",
+        indextemplate="pair: %s; django-admin command-line option",
+        parse_node=parse_django_adminopt_node,
+    )
+
+
+def parse_django_admin_node(env, sig, signode):
+    command = sig.split(' ')[0]
+    env._django_curr_admin_command = command
+    title = "django-admin.py %s" % sig
+    signode += addnodes.desc_name(title, title)
+    return sig
+
+
+def parse_django_adminopt_node(env, sig, signode):
+    """A copy of sphinx.directives.CmdoptionDesc.parse_signature()"""
+    from sphinx.domains.std import option_desc_re
+    count = 0
+    firstname = ''
+    for m in option_desc_re.finditer(sig):
+        optname, args = m.groups()
+        if count:
+            signode += addnodes.desc_addname(', ', ', ')
+        signode += addnodes.desc_name(optname, optname)
+        signode += addnodes.desc_addname(args, args)
+        if not count:
+            firstname = optname
+        count += 1
+    if not count:
+        for m in simple_option_desc_re.finditer(sig):
+            optname, args = m.groups()
+            if count:
+                signode += addnodes.desc_addname(', ', ', ')
+            signode += addnodes.desc_name(optname, optname)
+            signode += addnodes.desc_addname(args, args)
+            if not count:
+                firstname = optname
+            count += 1
+    if not firstname:
+        raise ValueError
+    return firstname

docs/conf.py

@@ -33,6 +33,10 @@ from example.example import settings
 from django.core.management import setup_environ
 setup_environ(settings)
 
+# For intersphinx
+ext_path = os.path.abspath(os.path.join(os.path.dirname(__file__), "_ext"))
+sys.path.append(ext_path)
+
 # -- General configuration -----------------------------------------------------
 
 # If your documentation needs a minimal Sphinx version, state it here.
@@ -40,7 +44,7 @@ setup_environ(settings)
 
 # Add any Sphinx extension module names here, as strings. They can be extensions
 # coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
-extensions = ['sphinx.ext.autodoc', 'sphinx.ext.intersphinx']
+extensions = ['djangodocs', 'sphinx.ext.autodoc', 'sphinx.ext.intersphinx']
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']
@@ -265,7 +269,6 @@ texinfo_documents = [
 
 # Example configuration for intersphinx: refer to the Python standard library.
 intersphinx_mapping = {
-    'django': (
-        'http://docs.djangoproject.com/en/dev/',
-        'http://docs.djangoproject.com/en/dev/_objects/'),
+    'python': ('http://python.readthedocs.org/en/v2.7.2/', None),
+    'django': ('http://docs.djangoproject.com/en/dev/', None),
 }

docs/ref/meta.rst

@@ -48,7 +48,8 @@ Attributes copied from ``Meta``
 
 Some of ``_meta``'s attributes are just copied from the ``Meta`` options. The
 following attributes are those. Their behaviour is more detailed described in
-the :doc:`django documentation <django:/ref/models/options>`.
+the `django documentation
+<https://docs.djangoproject.com/en/dev/ref/models/options/>`__.
 
 ``abstract``
     A boolean value.
@@ -87,7 +88,9 @@ the :doc:`django documentation <django:/ref/models/options>`.
     :attr:`~django.db.models.Options.get_latest_by`.
 
 ``managed``
-    If ``managed`` is ``True`` then the :djadmin:`syncdb` management command will take care of creating the database tables. Defaults to ``True``.
+    If ``managed`` is ``True`` then the :django:djadmin:`syncdb` management
+    command will take care of creating the database tables. Defaults to
+    ``True``.
 
     Also see the django documentation about
     :attr:`~django.db.models.Options.managed`.