Skip to content

api.rst

Latest commit

 

History

History
171 lines (117 loc) · 4.58 KB

api.rst

File metadata and controls

171 lines (117 loc) · 4.58 KB
Raw

API References

The Render Pipeline

The pipeline defines how nodes carrying data are generated and when they are rendered as part of the document.

  1. Generation: :py:class:`~sphinxnotes.render.BaseContextRole`, :py:class:`~sphinxnotes.render.BaseContextDirective` and their subclasses create :py:class:`~sphinxnotes.render.pending_node` on document parsing, and the node will be inserted to the document tree. The node contains:
  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

.. autoclass:: sphinxnotes.render.pending_node

Context

Context refers to the dynamic content of a Jinja template. It can be:

:py:class:`~sphinxnotes.render.ResolvedContext`:
Our dedicated data type (:py:class:`sphinxnotes.render.ParsedData`), or any Python dict.
:py:class:`~sphinxnotes.render.PendingContext`:

Context that is not yet available. For example, it may contain :py:class:`unparsed data <sphinxnotes.render.RawData>`, remote data, and more.

:py:class:`PendingContext` can be resolved to :py:class:`~sphinxnotes.render.ResolvedContext` by calling :py:meth:`~sphinxnotes.render.PendingContext.resolve`.

.. autotype:: sphinxnotes.render.ResolvedContext


.. autoclass:: sphinxnotes.render.PendingContext
   :members: resolve

PendingContext Implementations

.. autoclass:: sphinxnotes.render.UnparsedData
   :show-inheritance:

Template

See :doc:`tmpl` for the higher-level guide.

.. autoclass:: sphinxnotes.render.Template
   :members:


.. autoclass:: sphinxnotes.render.Phase
   :members:

Extra Context

See :doc:`tmpl` for built-in extra-context names such as doc and sphinx, plus usage examples.

.. autofunction:: sphinxnotes.render.extra_context


.. autoclass:: sphinxnotes.render.ParsingPhaseExtraContext
   :members: phase, generate
   :undoc-members:


.. autoclass:: sphinxnotes.render.ParsedPhaseExtraContext
   :members: phase, generate
   :undoc-members:


.. autoclass:: sphinxnotes.render.ResolvingPhaseExtraContext
   :members: phase, generate
   :undoc-members:


.. autoclass:: sphinxnotes.render.GlobalExtraContext
   :members: phase, generate
   :undoc-members:

Base Roles and Directives

For a minimal end-to-end example of a custom directive, start with :doc:`usage`.

Base Role Classes

.. autoclass:: sphinxnotes.render.BaseContextRole
   :show-inheritance:
   :members: process_pending_node, queue_pending_node, queue_context, current_context, current_template


.. autoclass:: sphinxnotes.render.BaseDataDefineRole
   :show-inheritance:
   :members: process_pending_node, queue_pending_node, queue_context, current_schema, current_template

Base Directive Classes

.. autoclass:: sphinxnotes.render.BaseContextDirective
   :show-inheritance:
   :members: process_pending_node, queue_pending_node, queue_context, current_context, current_template


.. autoclass:: sphinxnotes.render.BaseDataDefineDirective
   :show-inheritance:
   :members: process_pending_node, queue_pending_node, queue_context, current_schema, current_template


.. autoclass:: sphinxnotes.render.StrictDataDefineDirective
   :show-inheritance:
   :members: derive

Data, Field and Schema

.. autotype:: sphinxnotes.render.PlainValue


.. autotype:: sphinxnotes.render.Value


.. autoclass:: sphinxnotes.render.RawData
   :members: name, attrs, content
   :undoc-members:


.. autoclass:: sphinxnotes.render.ParsedData
   :members: name, attrs, content
   :undoc-members:


.. autoclass:: sphinxnotes.render.Field
   :members: parse


.. autoclass:: sphinxnotes.render.Schema
   :members: name, attrs, content
   :undoc-members:


.. autoclass:: sphinxnotes.render.data.Registry
   :members:

   .. autotype:: sphinxnotes.render.data.ByOptionStore

Registry

Developers can extend this extension (for example, to support more data types or add new extra context) by adding new items to :py:class:`sphinxnotes.render.REGISTRY`.

.. autodata:: sphinxnotes.render.REGISTRY


.. autoclass:: sphinxnotes.render.Registry

   .. autoproperty:: data