diff --git a/docs/_ext/djangodocs.py b/docs/_ext/djangodocs.py new file mode 100644 index 0000000..a88a9f8 --- /dev/null +++ b/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 diff --git a/docs/conf.py b/docs/conf.py index afa2358..4c2e76e 100644 --- a/docs/conf.py +++ b/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), } diff --git a/docs/ref/meta.rst b/docs/ref/meta.rst index d54b050..926c8fd 100644 --- a/docs/ref/meta.rst +++ b/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 `. +the `django documentation +`__. ``abstract`` A boolean value. @@ -87,7 +88,9 @@ the :doc:`django documentation `. :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`.