fix #187

Author: bckohan

doc/source/changelog.rst

@@ -2,6 +2,12 @@
 Change Log
 ==========
 
+v3.3.1 (2025-07-16)
+===================
+
+* Added `Convert docs to intersphinx references. <https://github.com/bckohan/django-render-static/issues/187>`_
+
+
 v3.3.0 (2025-03-12)
 ====================
 

doc/source/commands.rst

@@ -4,11 +4,11 @@
 Commands
 ========
 
-.. _renderstatic:
-
 renderstatic
 ------------
 
+.. django-admin:: renderstatic
+
 .. automodule:: render_static.management.commands.renderstatic
 
 Usage
@@ -22,16 +22,16 @@ Usage
 Example
 ~~~~~~~
 
-To generate all templates configured in ``STATIC_TEMPLATES`` settings:
+To generate all templates configured in :setting:`STATIC_TEMPLATES` settings:
 
-.. code::
+.. code-block:: bash
 
     $ manage.py renderstatic
 
-Alternatively individual templates can be generated, regardless of their presence
-in ``STATIC_TEMPLATES``. They will be given the global context with any overriding context
+Alternatively individual templates can be generated, regardless of their presence in
+:setting:`STATIC_TEMPLATES`. They will be given the global context with any overriding context
 parameters supplied on the command line:
 
-.. code::
+.. code-block:: bash
 
     $ manage.py renderstatic path/*.js -c ./js_context.yaml -d outputdir

doc/source/conf.py

@@ -28,15 +28,11 @@
 
 
 # -- Project information -----------------------------------------------------
-
-project = 'django-render-static'
-copyright = f'2020-{datetime.now().year}, Brian Kohan'
-author = 'Brian Kohan'
-
-# The full version, including alpha/beta/rc tags
+project = render_static.__title__
+copyright = render_static.__copyright__
+author = render_static.__author__
 release = render_static.__version__
 
-
 # -- General configuration ---------------------------------------------------
 
 # Add any Sphinx extension module names here, as strings. They can be
@@ -46,7 +42,9 @@
     'sphinx.ext.autodoc',
     'sphinx.ext.viewcode',
     'sphinx.ext.todo',
-    'sphinxcontrib.typer'
+    'sphinxcontrib.typer',
+    'sphinx.ext.intersphinx',
+    'sphinxcontrib_django'
     # 'sphinx_js'
 ]
 
@@ -82,3 +80,36 @@
 #   str(Path(__file__).parent.parent.parent / 'render_static' / 'tests' /
 #   'examples' / 'static' / 'examples'
 # )
+
+autodoc_default_options = {
+    'show-inheritance': True,
+    # Add other autodoc options here if desired, e.g.:
+    # 'members': True,
+    # 'inherited-members': True,
+}
+
+intersphinx_mapping = {
+    "django": (
+        "https://docs.djangoproject.com/en/stable",
+        "https://docs.djangoproject.com/en/stable/_objects/",
+    ),
+    "django-typer": ("https://django-typer.readthedocs.io/en/stable", None),
+    "enum-properties": ("https://enum-properties.readthedocs.io/en/stable", None),
+    "django-enum": ("https://django-enum.readthedocs.io/en/stable", None),
+    "jinja": ("https://jinja.palletsprojects.com/en/stable", None),
+    "python": ('https://docs.python.org/3', None)
+}
+
+def pypi_role(name, rawtext, text, lineno, inliner, options={}, content=[]):
+    from docutils import nodes
+    url = f"https://pypi.org/project/{text}/"
+    node = nodes.reference(rawtext, text, refuri=url, **options)
+    return [node], []
+
+def setup(app):
+    # Register a sphinx.ext.autodoc.between listener to ignore everything
+    # between lines that contain the word IGNORE
+    from docutils.parsers.rst import roles
+    app.add_crossref_type(directivename="django-admin", rolename="django-admin")
+    roles.register_local_role('pypi', pypi_role)
+    return app

doc/source/configuration.rst

@@ -4,8 +4,8 @@
 Configuration
 =============
 
-`django-render-static` settings are set in the ``STATIC_TEMPLATES`` dictionary in your site
-settings:
+:pypi:`django-render-static` settings are set in the :setting:`STATIC_TEMPLATES` dictionary in your
+site settings:
 
 .. code-block:: python
 
@@ -37,19 +37,20 @@ settings:
         ]
       }
 
-The ``STATIC_TEMPLATES`` setting closely mirrors the ``TEMPLATES`` setting by defining which
-template backends should be used. It extends the standard setting with a few options needed by the
-static engine including a global context available to all static templates and a set of template
-specific configuration parameters. It's advisable to first read about Django's ``TEMPLATES``
-setting. The main difference with ``STATIC_TEMPLATES`` is that it supports batch rendering.
+The :setting:`STATIC_TEMPLATES` setting closely mirrors the :setting:`TEMPLATES` setting by defining
+which template backends should be used. It extends the standard setting with a few options needed by
+the static engine including a global context available to all static templates and a set of template
+specific configuration parameters. It's advisable to first read about Django's :setting:`TEMPLATES`
+setting. The main difference with :setting:`STATIC_TEMPLATES` is that it supports batch rendering.
 Glob-like patterns can be used to select multiple templates for rendering. See :ref:`loaders` for
 more details.
 
 Minimal Configuration
 ---------------------
 
-To run `renderstatic`, If ``STATIC_TEMPLATES`` is not defined in settings. Or, if it's an empty
-dictionary (or None) then the default engine and loaders will be used which is equivalent to:
+To run :django-admin:`renderstatic`, If :setting:`STATIC_TEMPLATES` is not defined in settings. Or,
+if it's an empty dictionary (or None) then the default engine and loaders will be used which is
+equivalent to:
 
 .. code-block:: python
 
@@ -69,17 +70,17 @@ dictionary (or None) then the default engine and loaders will be used which is e
 -----------
 
 A prioritized list of backend template engines and their parameters. The engines at the front of the
-list have precedence over engines further down the list. The ``ENGINES`` parameters are
-inherited from the standard Django ``TEMPLATES`` configuration.
+list have precedence over engines further down the list. The ``ENGINES`` parameters are inherited
+from the standard Django :setting:`TEMPLATES` configuration.
 
 ``BACKEND``
 ~~~~~~~~~~~
-The backend classes that render templates. The standard ``TEMPLATES`` engines should not be used
-here, instead use the two engines provided by `django-render-static`:
+The backend classes that render templates. The standard :setting:`TEMPLATES` engines should not be
+used here, instead use the two engines provided by :pypi:`django-render-static`:
 
-- ``render_static.backends.StaticDjangoTemplates``
-    - default app directory: ``static_templates``
-- ``render_static.backends.jinja2.StaticJinja2Templates``
+- :class:`render_static.backends.StaticDjangoTemplates`
+    - default app directory: :setting:`STATIC_TEMPLATES`
+- :class:`render_static.backends.jinja2.StaticJinja2Templates`
     - default app directory: ``static_jinja2``
 
 If ``APP_DIRS`` is true, or if an app directories loader is used such that templates are searched
@@ -93,55 +94,57 @@ parameter into ``OPTIONS``.
 A list of configuration parameters to pass to the backend during initialization. Most of these
 parameters are inherited from the standard Django template backends. One additional parameter
 ``app_dir`` can be used to change the default search path for static templates within apps. The
-`options available to the StaticDjangoTemplates backend <https://docs.djangoproject.com/en/stable/topics/templates/#django.template.backends.django.DjangoTemplates>`_
-differ slightly from the `options available to the StaticJinja2Templates backend <https://docs.djangoproject.com/en/stable/topics/templates/#django.template.backends.jinja2.Jinja2>`_.
+:class:`options available to the StaticDjangoTemplates backend <django.template.backends.django.DjangoTemplates>`
+differ slightly from the :class:`options available to the StaticJinja2Templates backend <django.template.backends.jinja2.Jinja2>`.
 
 .. _loaders:
 
 ``loader(s)``
 *************
 
-Works the same way as the ``loaders`` parameter on ``TEMPLATES``. Except when using the standard
-template backend the loaders have been extended and static specific loaders should be used instead:
+Works the same way as the ``loaders`` parameter on :setting:`TEMPLATES`. Except when using the
+standard template backend the loaders have been extended and static specific loaders should be used
+instead:
 
-- ``render_static.backends.StaticDjangoTemplates``
-    - ``render_static.loaders.django.StaticAppDirectoriesBatchLoader`` **default**
-    - ``render_static.loaders.django.StaticFilesystemBatchLoader``
-    - ``render_static.loaders.django.StaticAppDirectoriesLoader``
-    - ``render_static.loaders.django.StaticFilesystemLoader``
-    - ``render_static.loaders.django.StaticLocMemLoader``
+- :class:`render_static.backends.StaticDjangoTemplates <render_static.backends.django.StaticDjangoTemplates>`
+    - :class:`render_static.loaders.django.StaticAppDirectoriesBatchLoader` **default**
+    - :class:`render_static.loaders.django.StaticFilesystemBatchLoader`
+    - :class:`render_static.loaders.django.StaticAppDirectoriesLoader`
+    - :class:`render_static.loaders.django.StaticFilesystemLoader`
+    - :class:`render_static.loaders.django.StaticLocMemLoader`
 
-- ``render_static.backends.jinja2.StaticJinja2Templates``
-    - ``render_static.loaders.jinja2.StaticFileSystemBatchLoader`` **default**
-    - ``render_static.loaders.jinja2.StaticFileSystemLoader``
-    - ``render_static.loaders.jinja2.StaticPackageLoader``
-    - ``render_static.loaders.jinja2.StaticPrefixLoader``
-    - ``render_static.loaders.jinja2.StaticFunctionLoader``
-    - ``render_static.loaders.jinja2.StaticDictLoader``
-    - ``render_static.loaders.jinja2.StaticChoiceLoader``
-    - ``render_static.loaders.jinja2.StaticModuleLoader``
+- :class:`render_static.backends.jinja2.StaticJinja2Templates`
+    - :class:`render_static.loaders.jinja2.StaticFileSystemBatchLoader` **default**
+    - :class:`render_static.loaders.jinja2.StaticFileSystemLoader`
+    - :class:`render_static.loaders.jinja2.StaticPackageLoader`
+    - :class:`render_static.loaders.jinja2.StaticPrefixLoader`
+    - :class:`render_static.loaders.jinja2.StaticFunctionLoader`
+    - :class:`render_static.loaders.jinja2.StaticDictLoader`
+    - :class:`render_static.loaders.jinja2.StaticChoiceLoader`
+    - :class:`render_static.loaders.jinja2.StaticModuleLoader`
 
 
 .. note::
-    The ``StaticJinja2Templates engine`` is configurable with only one loader
-    and the parameter is called ``loader``. The ``StaticDjangoTemplates``
-    engine is configurable with more than one loader that are specified as a
-    list under the ``loaders`` parameter.
+
+    The :class:`~render_static.backends.jinja2.StaticJinja2Templates` engine is configurable with
+    only one loader and the parameter is called ``loader``. The
+    :class:`~render_static.backends.django.StaticDjangoTemplates` engine is configurable with more
+    than one loader that are specified as a list under the ``loaders`` parameter.
 
 
 The static template engine supports batch rendering. All loaders that have ``Batch`` in the name
 support wild cards and glob-like patterns when loading templates. By default, if no loaders are
-specified these loaders are used. For instance, if I wanted to render every .js file in a
-directory called static_templates/js I could configure templates like so:
+specified these loaders are used. For instance, if I wanted to render every .js file in a directory
+called static_templates/js I could configure templates like so:
 
 .. code-block:: python
 
     'templates': ['js/*.js']
 
 ``context``
 -----------
-Specify a dictionary containing the context to pass to any static templates as they render. This
-is the global context that will be applied to all templates. Specific templates can override
+Specify a dictionary containing the context to pass to any static templates as they render. This is
+the global context that will be applied to all templates. Specific templates can override
 individual context parameters, but not the whole dictionary. By default all contexts will have the
 Django settings in them, keyed by ``settings``.
 
@@ -177,15 +180,18 @@ For example:
       }
 
 
-``templates``
--------------
+``STATIC_TEMPLATES``
+--------------------
+
+.. setting:: STATIC_TEMPLATES
 
-The ``templates`` dictionary lists all templates that should be generated when `renderstatic` is
-run with no arguments. If specific configuration directives including rendered path and context are
-needed for a template they must be specified here. ``templates`` may also be a list containing
-template names or 2-tuples of template names and configurations. By specifying ``templates`` this
-way, a single template may be rendered multiple times using different contexts to different
-locations. For example, the following would render one template three times:
+The :setting:`STATIC_TEMPLATES` dictionary lists all templates that should be generated when
+:django-admin:`renderstatic` is run with no arguments. If specific configuration directives
+including rendered path and context are needed for a template they must be specified here.
+:setting:`STATIC_TEMPLATES` may also be a list containing template names or 2-tuples of template
+names and configurations. By specifying :setting:`STATIC_TEMPLATES` this way, a single template may
+be rendered multiple times using different contexts to different locations. For example, the
+following would render one template three times:
 
 .. code-block:: python
 
@@ -198,9 +204,9 @@ locations. For example, the following would render one template three times:
 
 .. note::
 
-    `renderstatic` will be able to generate templates not listed in ``templates``, but only if
-    supplied by name on the command line. Contexts may also be augmented/overridden via the command
-    line.
+    :django-admin:`renderstatic` will be able to generate templates not listed in
+    :setting:`STATIC_TEMPLATES`, but only if supplied by name on the command line. Contexts may
+    also be augmented/overridden via the command line.
 
 ``dest``
 ~~~~~~~~
@@ -226,27 +232,30 @@ any of the same context specifiers that work for the global context.
 ``RENDER_STATIC_REVERSAL_LIMIT``
 --------------------------------
 
-The guess and check reversal mechanism used to ensure that `urls_to_js` produces the same reversals
-as Django's `reverse` is an **O(n^p)** operation where **n** is the number of placeholder candidates
-to try and **p** is the number of arguments in the url. Its possible for this to produce a
-complexity explosion for rare cases where the URL has a large number of arguments with unregistered
-placeholders. A limit on the number of tries is enforced to guard against this. User's may adjust
-the limit via the ``RENDER_STATIC_REVERSAL_LIMIT`` settings parameter. By default it is 2**14 tries
-which runs in ~seconds per URL.
+.. setting:: RENDER_STATIC_REVERSAL_LIMIT
+
+The guess and check reversal mechanism used to ensure that :templatetag:`urls_to_js` produces the
+same reversals as Django's :func:`~django.urls.reverse` is an **O(n^p)** operation where **n** is
+the number of placeholder candidates to try and **p** is the number of arguments in the url. Its
+possible for this to produce a complexity explosion for rare cases where the URL has a large number
+of arguments with unregistered placeholders. A limit on the number of tries is enforced to guard
+against this. User's may adjust the limit via the :setting:`RENDER_STATIC_REVERSAL_LIMIT`` settings
+parameter. By default it is 2**14 tries which runs in ~seconds per URL.
 
 The solution if this limit is hit, is to provide more specific placeholders as placeholders are
-attempted in order of specificity where specificity is defined by url name, variable name,
-app name and/or converter type.
+attempted in order of specificity where specificity is defined by url name, variable name, app name
+and/or converter type.
 
 
-``StaticJinja2Templates`` Example
----------------------------------
+:class:`~render_static.backends.jinja2.StaticJinja2Templates` Example
+---------------------------------------------------------------------
 
-Using the ``StaticJinja2Template`` engine requires a slightly different configuration. By
-default the ``render_static.loaders.jinja2.StaticFileSystemBatchLoader`` loader is used
-and its ``app_dir`` setting will expect to find templates in static_jinja2 sub directories.
-For example to render all urls except our admin urls to javascript using (:ref:`urls_to_js`)
-we might have the following app tree::
+Using the :class:`~render_static.backends.jinja2.StaticJinja2Templates` engine requires a slightly
+different configuration. By default the
+:class:`render_static.loaders.jinja2.StaticFileSystemBatchLoader` loader is used and its
+``app_dir`` setting will expect to find templates in static_jinja2 sub directories. For example to
+render all urls except our admin urls to javascript using :templatetag:`urls_to_js` we might have
+the following app tree::
 
     .
     └── my_app
@@ -255,8 +264,8 @@ we might have the following app tree::
         ├── defines.py
         ├── models.py
         ├── static_jinja2
-        │   └── my_app
-        │       └── urls.js
+        │   └── my_app
+        │       └── urls.js
         └── urls.py
 
 Where our urls.js file might look like: