Merge pull request #8 from sphinx-notes/tmpl

docs: Add tmpl.rst

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,11 @@
 
 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
+
+    sys.path.insert(0, os.path.abspath('../tests/roots/test-ctxdir-usage'))
+    from conf import setup as setup_ctxdir_usage_example
+    setup_ctxdir_usage_example(app)

docs/index.rst

@@ -39,8 +39,16 @@ Getting Started
 
 .. note::
 
-   This extension is not intended to be used directly by Sphinx users.
-   It is for Sphinx extension developers.
+   This extension is **aimed at advanced Sphinx users or extension developers**.
+
+   If you are new to Sphinx, you may instersting with
+   :parsed_literal:`sphinxnotes.data__` or :parsed_literal:`sphinxnotes.any__`.
+
+   __ https://sphinx.silverrainz.me/data
+   __ https://sphinx.silverrainz.me/any
+
+We cannot get you started with this short section; please refer to the
+:doc:`usage` for more detailed information.
 
 .. ADDITIONAL CONTENT END
 
@@ -49,8 +57,10 @@ Contents
 
 .. toctree::
    :caption: Contents
+   :maxdepth: 2
 
    usage
+   tmpl
    dsl
    api
    changelog