docs: Tweak tweak

Author: SilverRainZ

docs/conf.py

@@ -136,3 +136,7 @@
 
 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,11 +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 the project, read :doc:`usage` first, then :doc:`tmpl`,
-   and finally :doc:`dsl` and :doc:`api` as reference material.
+   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
 

docs/tmpl.rst

@@ -2,18 +2,53 @@
 Templating
 ==========
 
-``sphinxnotes.render`` uses Jinja2_ to turn structured context data into markup
-text, usually reStructuredText. The rendered text is then parsed again by
-Sphinx/docutils and inserted into the document.
-
 This page focuses on the context made available to templates, when that context
 is available, and how extension authors can add more of it. You should already
 be comfortable with basic Jinja2 syntax before reading this page.
 
 .. _Jinja2: https://jinja.palletsprojects.com/en/stable/templates/
 
-Directive Data Context
-======================
+Jinja Environment
+=================
+
+Templates are rendered in a sandboxed Jinja2 environment.
+
+- Undefined variables raise errors by default (``undefined=DebugUndefined``)
+- Extension ``jinja2.ext.loopcontrols``, ``jinja2.ext.do`` are enabled by default.
+- Output is plain markup text, so you can generate lists, directives, roles,
+  and other reStructuredText constructs.
+
+Built-in filters
+----------------
+
+``role``
+   We provides a ``roles`` filter for producing role markup from a sequence of
+   strings.
+
+   .. example::
+      :style: grid
+
+      .. data.render::
+
+         {%
+         set text = ['index', 'usage']
+                    | roles('doc')
+                    | join(', ')
+         %}
+
+         :Text: ``{{ text }}``
+         :Rendered: {{ text }}
+
+Extending filters
+-----------------
+
+To be done.
+
+Context
+=======
+
+Directive and Role Context
+--------------------------
 
 When a directive or role provides data through
 :py:class:`~sphinxnotes.render.BaseDataDefineDirective` or
@@ -43,43 +78,43 @@ The following `template variables`_ are available in the main context:
 
             {{ name }}
 
-         .. data.define:: foo
+         .. data.define:: This is the argument
 
       For role, this is not available for now.
 
    ``{{ attrs.xxx }}``
       For directive, this refer to the directive options.
       It is a mapping of option's field to its value, so
-      ``{{ attrs.color }}`` and ``{{ attrs['color'] }}`` are equivalent.
+      ``{{ attrs.label }}`` and ``{{ attrs['label'] }}`` are equivalent.
 
       .. example::
          :style: grid
 
          .. data.template::
 
-            Color is {{ attrs.color }}.
+            Label is {{ attrs.label }}.
 
-         .. data::
-            :color: red
+         .. data.define::
+            :label: Important
 
       For role, this is not available for now.
 
       .. note::
 
          Attribute values are also lifted to the top-level template context when
-         there is no name conflict. For example, ``{{ color }}`` can be used
-         instead of ``{{ attrs.color }}``, but ``{{ name }}`` still refers to
+         there is no name conflict. For example, ``{{ label }}`` can be used
+         instead of ``{{ attrs.label }}``, but ``{{ name }}`` still refers to
          the data object's own ``name`` field.
 
          .. example::
             :style: grid
 
             .. data.template::
 
-               {{ color }} and {{ attrs.color }} are same.
+               {{ label }} and {{ attrs.label }} are same.
 
-            .. data::
-               :color: red
+            .. data.define::
+               :label: Important
 
    ``{{ content }}``
       For directive, this refer to the directive body.
@@ -91,9 +126,9 @@ The following `template variables`_ are available in the main context:
 
             {{ content }}
 
-         .. data::
-            
-            Color is red.
+         .. data.define::
+
+            This is the body content.
 
       For role, this refer to the interpreted text.
 
@@ -104,7 +139,7 @@ The following `template variables`_ are available in the main context:
 
             {{ content }}
 
-         :data:`Color is red`
+          :data:`This is the interpreted text`
 
 The type of each variable depends on the corresponding :py:class:`~sphinxnote.render.Schema`.
 For developers, the schema is provided by the
@@ -114,15 +149,13 @@ For example, for the `sphinxnotes.data` extension, the schema is defined through
 the :rst:dir:`data.schema` directive.
 
 Extra Context
-=============
-
-TODO: Refactor
+-------------
 
 Templates may also receive extra context entries in addition to the main data
 context. These entries are stored under names prefixed with ``_``.
 
 Built-in extra context
-----------------------
+......................
 
 .. list-table::
    :header-rows: 1
@@ -156,83 +189,30 @@ arbitrary Python object behavior.
 
    .. data.render::
 
-      Current document title is {{ _doc.title }}.
+      Current document title is
+      "{{ _doc.title }}".
 
 Extending extra context
------------------------
+.......................
 
 Extension authors can register more context generators through
 :py:data:`sphinxnotes.render.REGISTRY`.
 
-.. code-block:: python
-
-   from sphinxnotes.render import REGISTRY, ParsePhaseExtraContext
-
-   class ProjectContext(ParsePhaseExtraContext):
-       def generate(self, host):
-           return {'lineno': host.lineno}
-
-
-   REGISTRY.extra_context.add_parsing_phase_context('project', ProjectContext())
-
-The registered context becomes available in templates as ``_project``.
-
-Depending on when the value can be computed, implement one of these base
-classes:
-
-- :py:class:`~sphinxnotes.render.GlobalExtraContxt` for context available in
-  every phase.
-- :py:class:`~sphinxnotes.render.ParsePhaseExtraContext` for context generated
-  during :py:data:`~sphinxnotes.render.Phase.Parsing`.
-- :py:class:`~sphinxnotes.render.ResolvePhaseExtraContext` for context generated
-  during :py:data:`~sphinxnotes.render.Phase.Parsed` or
-  :py:data:`~sphinxnotes.render.Phase.Resolving`.
-
-Jinja Environment
-=================
-
-Templates are rendered in a sandboxed Jinja2 environment.
-
-- Undefined variables raise errors by default (``undefined=DebugUndefined``)
-- Extension ``jinja2.ext.loopcontrols``, ``jinja2.ext.do`` are enabled by default.
-- Output is plain markup text, so you can generate lists, directives, roles,
-  and other reStructuredText constructs.
-
-Built-in filters
-----------------
-
-``role``
-   We provides a ``roles`` filter for producing role markup from a sequence of
-   strings.
-
-   .. example::
-      :style: grid
-
-      .. data.render::
-      
-         {%
-         set text = ['index', 'usage']
-                    | roles('doc')
-                    | join(', ')
-         %}
-
-         :Text: ``{{ text }}``
-         :Rendered: {{ text }}
+TODO.
 
-Extending filters
------------------
+Template
+========
 
-To be done.
-Phases
-======
+Render Phases
+-------------
 
 Each :py:class:`~sphinxnotes.render.Template` has a render phase controlled by
 :py:class:`~sphinxnotes.render.Phase`.
 
 ``parsing`` (:py:data:`sphinxnotes.render.Phase.Parsing`)
    Render immediately while the directive or role is running.
 
-   This is the default render pahse.
+   This is the default render phase.
    Choose this when the template only needs local information and does not rely
    on the final doctree or cross-document state.
 
@@ -243,9 +223,11 @@ Each :py:class:`~sphinxnotes.render.Template` has a render phase controlled by
          :on: parsing
 
          - The current document has
-           {{ _doc.sections | length }} section(s).
+           {{ _doc.sections | length }}
+           section(s).
          - The current project has
-           {{ _sphinx.env.all_docs | length }} document(s).
+           {{ _sphinx.env.all_docs | length }}
+           document(s).
 
 ``parsed`` (:py:data:`sphinxnotes.render.Phase.Parsed`)
    Render after the current document has been parsed.
@@ -260,9 +242,11 @@ Each :py:class:`~sphinxnotes.render.Template` has a render phase controlled by
          :on: parsed
 
          - The current document has
-           {{ _doc.sections | length }} section(s).
+           {{ _doc.sections | length }}
+           section(s).
          - The current project has
-           {{ _sphinx.env.all_docs | length }} document(s).
+           {{ _sphinx.env.all_docs | length }}
+           document(s).
 
 ``resolving`` (:py:data:`sphinxnotes.render.Phase.Resolving`)
    Render late in the build, after references and other transforms are being
@@ -278,9 +262,22 @@ Each :py:class:`~sphinxnotes.render.Template` has a render phase controlled by
          :on: resolving
 
          - The current document has
-           {{ _doc.sections | length }} section(s).
+           {{ _doc.sections | length }}
+           section(s).
          - The current project has
-           {{ _sphinx.env.all_docs | length }} document(s).
+           {{ _sphinx.env.all_docs | length }}
+           document(s).
+
+Debugging
+---------
+
+Set :py:attr:`sphinxnotes.render.Template.debug` to ``True`` to append a debug
+report to the rendered document. The report includes the resolved context,
+available extra-context keys, the template source, the rendered markup text,
+and the final nodes produced from that markup.
+
+This is especially useful when a template fails because of an undefined
+variable, unexpected data shape, or invalid generated markup.
 
 End-to-End Example
 ==================
@@ -316,14 +313,3 @@ This pattern is often the most convenient way to build small, declarative
 directives. For more control, subclass
 :py:class:`~sphinxnotes.render.BaseDataDefineDirective` directly and implement
 ``current_schema()`` and ``current_template()`` yourself.
-
-Debugging
-=========
-
-Set :py:attr:`sphinxnotes.render.Template.debug` to ``True`` to append a debug
-report to the rendered document. The report includes the resolved context,
-available extra-context keys, the template source, the rendered markup text,
-and the final nodes produced from that markup.
-
-This is especially useful when a template fails because of an undefined
-variable, unexpected data shape, or invalid generated markup.

docs/usage.rst

@@ -8,12 +8,18 @@ Usage
    :external+sphinx:doc:`development/tutorials/extending_syntax`.
    See how to extend :py:class:`SphinxDirective` and :py:class:`SphinxRole`.
 
+``sphinxnotes.render`` uses Jinja2_ to turn structured data into markup
+text, usually reStructuredText. The rendered text is then parsed again by
+Sphinx and inserted into the document.
+
+.. _Jinja2: https://jinja.palletsprojects.com/en/stable/templates/
+
+Now we have a quick example to help you get Started.
 Create a Sphinx documentation with the following ``conf.py``:
 
 .. literalinclude:: ../tests/roots/test-ctxdir-usage/conf.py
 
-This is the smallest useful extension built on top of
-``sphinxnotes.render``:
+This is the smallest useful extension built on top of ``sphinxnotes.render``:
 
 - it defines a custom directive by subclassing
   :py:class:`~sphinxnotes.render.BaseContextDirective`
@@ -25,12 +31,11 @@ This is the smallest useful extension built on top of
 
 Now use the directive in your document:
 
-.. code-block:: rst
+.. example::
+   :style: grid
 
    .. me::
-
-This will render as: My name is Shengyu Zhang.
-
+ 
 Next steps
 ==========