docs: Expand templating guide

Author: SilverRainZ

docs/api.rst

@@ -16,13 +16,16 @@ rendered as part of the document.
    - :ref:`context`, the dynamic content of a Jinja template
 
    - :py:class:`~sphinxnotes.render.Template`,
-     the Jinja template for rendering context to markup text
-     (reStructuredText or Markdown)
+      the Jinja template for rendering context to markup text
+      (reStructuredText or Markdown)
 
 2. Render: the ``pending_node`` node will be rendered at the appropriate
    :py:class:`~sphinxnotes.render.Phase`, depending on
    :py:attr:`~sphinxnotes.render.pending_node.template.phase`.
 
+For a task-oriented explanation of template variables, extra context, and phase
+selection, see :doc:`tmpl`.
+
 Node
 -----
 
@@ -64,6 +67,8 @@ Context refers to the dynamic content of a Jinja template. It can be:
 Template
 --------
 
+See :doc:`tmpl` for the higher-level guide.
+
 .. autoclass:: sphinxnotes.render.Template
    :members:
 
@@ -73,6 +78,9 @@ Template
 Extra Context
 -------------
 
+See :doc:`tmpl` for built-in extra-context names such as ``_doc`` and
+``_sphinx``, plus usage examples.
+
 .. autoclass:: sphinxnotes.render.GlobalExtraContxt
 
 .. autoclass:: sphinxnotes.render.ParsePhaseExtraContext
@@ -86,6 +94,8 @@ Extra Context
 Base Roles and Directives
 -------------------------
 
+For a minimal end-to-end example of a custom directive, start with :doc:`usage`.
+
 Base Role Classes
 ~~~~~~~~~~~~~~~~~
 

docs/conf.py

@@ -122,6 +122,8 @@
 sys.path.insert(0, os.path.abspath('../src/'))
 extensions.append('sphinxnotes.render')
 
+extensions.append('sphinxnotes.data')
+
 # CUSTOM CONFIGURATION
 
 autodoc_default_options = {
@@ -130,6 +132,7 @@
 
 intersphinx_mapping['python'] = ('https://docs.python.org/3', None)
 intersphinx_mapping['sphinx'] = ('https://www.sphinx-doc.org/en/master', None)
+intersphinx_mapping['data'] = ('https://sphinx.silverrainz.me/data', None)
 
 def setup(app):
     app.add_object_type('event', 'event') # for intersphinx

docs/index.rst

@@ -42,13 +42,17 @@ Getting Started
    This extension is not intended to be used directly by Sphinx users.
    It is for Sphinx extension developers.
 
+   If you are new to the project, read :doc:`usage` first, then :doc:`tmpl`,
+   and finally :doc:`dsl` and :doc:`api` as reference material.
+
 .. ADDITIONAL CONTENT END
 
 Contents
 ========
 
 .. toctree::
    :caption: Contents
+   :maxdepth: 2
 
    usage
    tmpl