Merge pull request #7 from sphinx-notes/autodocs-improvement

Detailed API docs

Author: SilverRainZ

.cruft.json

@@ -1,6 +1,6 @@
 {
   "template": "https://github.com/sphinx-notes/cookiecutter",
-  "commit": "62cd96195962da3392cdc34125c95e9144a5f5ca",
+  "commit": "4c6b17aec1a4b8ddca95c4882c6bed2bc230d595",
   "checkout": null,
   "context": {
     "cookiecutter": {
@@ -20,7 +20,7 @@
       "sphinx_version": "7.0",
       "development_status": "3 - Alpha",
       "_template": "https://github.com/sphinx-notes/cookiecutter",
-      "_commit": "62cd96195962da3392cdc34125c95e9144a5f5ca"
+      "_commit": "4c6b17aec1a4b8ddca95c4882c6bed2bc230d595"
     }
   },
   "directory": null

docs/api.rst

@@ -1,64 +1,151 @@
-=============
-API Reference
-=============
+==============
+API References
+==============
 
-Data Types
-==========
+The Render Pipeline
+===================
 
-.. autotype:: sphinxnotes.render.PlainValue
-.. autotype:: sphinxnotes.render.Value
+The pipeline defines how nodes carrying data are generated and when they are
+rendered as part of the document.
 
-.. autoclass:: sphinxnotes.render.RawData
-.. autoclass:: sphinxnotes.render.ParsedData
+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:
 
-.. autoclass:: sphinxnotes.render.Field
-.. autoclass:: sphinxnotes.render.Schema
+   - :ref:`context`, the dynamic content of a Jinja template
 
-.. autoclass:: sphinxnotes.render.data.Registry
+   - :py:class:`~sphinxnotes.render.Template`,
+     the Jinja template for rendering context to markup text
+     (reStructuredText or Markdown)
 
-   .. automethod:: add_type
-   .. automethod:: add_form
-   .. automethod:: add_flag
-   .. automethod:: add_by_option
+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`.
 
-      .. autotype:: sphinxnotes.render.data.ByOptionStore
+Node
+-----
 
-The Render Pipeline
-===================
+.. autoclass:: sphinxnotes.render.pending_node
+
+.. _context:
 
 Context
 -------
 
-.. autoclass:: sphinxnotes.render.PendingContext
+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.UnparsedData
 
-.. autoclass:: sphinxnotes.render.pending_node
+.. autoclass:: sphinxnotes.render.PendingContext
+   :members: resolve
 
-Extra Context
--------------
+``PendingContext`` Implementations
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-.. autoclass:: sphinxnotes.render.ExtraContextGenerator
-.. autoclass:: sphinxnotes.render.ExtraContextRegistry
+.. autoclass:: sphinxnotes.render.UnparsedData
+   :show-inheritance:
+
+.. _extractx:
 
 Template
 --------
 
 .. autoclass:: sphinxnotes.render.Template
+   :members:
+
 .. autoclass:: sphinxnotes.render.Phase
+   :members:
 
-Pipeline
---------
+Extra Context
+-------------
+
+.. autoclass:: sphinxnotes.render.GlobalExtraContxt
+
+.. autoclass:: sphinxnotes.render.ParsePhaseExtraContext
+
+.. autoclass:: sphinxnotes.render.ResolvePhaseExtraContext
+
+.. autoclass:: sphinxnotes.render.ExtraContextRegistry
+   :members:
+
+
+Base Roles and Directives
+-------------------------
+
+Base Role Classes
+~~~~~~~~~~~~~~~~~
 
 .. autoclass:: sphinxnotes.render.BaseContextRole
-.. autoclass:: sphinxnotes.render.BaseContextDirective
+   :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

docs/conf.py

@@ -24,6 +24,7 @@
 extensions = [
     'sphinx.ext.githubpages',
     'sphinx.ext.doctest',
+    'sphinx.ext.viewcode',
     'sphinx_design',
     'sphinx_copybutton',
     'sphinx_last_updated_by_git',
@@ -118,12 +119,17 @@
 # documentation root, use os.path.abspath to make it absolute, like shown here.
 import os
 import sys
-sys.path.insert(0, os.path.abspath('../src/sphinxnotes'))
-extensions.append('render')
+sys.path.insert(0, os.path.abspath('../src/'))
+extensions.append('sphinxnotes.render')
 
 # CUSTOM CONFIGURATION
 
-_ = extensions.pop() # no need to load extension
-primary_domain = 'py'
+autodoc_default_options = {
+    'member-order': 'bysource',
+}
+
+intersphinx_mapping['python'] = ('https://docs.python.org/3', None)
+intersphinx_mapping['sphinx'] = ('https://www.sphinx-doc.org/en/master', None)
 
-extensions.append('sphinx.ext.doctest')
+def setup(app):
+    app.add_object_type('event', 'event') # for intersphinx

docs/dsl.rst

@@ -1,26 +1,16 @@
-=====================
-Field Declaration DSL
-=====================
+==========================
+Field Description Language
+==========================
 
 .. default-domain:: py
 .. highlight:: python
 .. role:: py(code)
    :language: Python
 
 
-The Field Declaration DSL is a Domain Specific Language (DSL) that used to
-define the type and structure of field values. A DSL declaration consists of
-one or more :term:`modifier`\ s separated by commas (``,``).
-
-Python API
-==========
-
-User can create a :class:`sphinxnotes.render.Field` from DSL and use it to parse
-string to :type:`sphinxnotes.render.Value`:
-
->>> from sphinxnotes.render import Field
->>> Field.from_dsl('list of int').parse('1,2,3')
-[1, 2, 3]
+The Field Description Language is a Domain Specific Language (DSL) that is used to
+define the type and structure of field values. An FDL declaration consists of
+one or more :term:`modifier` entries separated by commas (``,``).
 
 Syntax
 ======
@@ -34,17 +24,28 @@ Syntax
    Modifier
       There are four categories of modifiers:
 
-      Type modifier
-         Specifies the element type (scalar value)
+   Type modifier
+      Specifies the element type (scalar value)
+
+   Form modifier
+      Specifies a container type with element type
 
-      Form modifier
-         Specifies a container type with element type
+   Flag
+      A boolean flag (either on or off)
 
-      Flag
-         A boolean flag (either on or off)
+   By-Option
+      A key-value option
+
+Python API
+==========
+
+Users can create a :class:`sphinxnotes.render.Field` from FDL and use it to parse
+strings into :type:`sphinxnotes.render.Value`:
+
+>>> from sphinxnotes.render import Field
+>>> Field.from_dsl('list of int').parse('1,2,3')
+[1, 2, 3]
 
-      By-Option
-         A key-value option
 
 Type
 ====
@@ -73,7 +74,7 @@ A type modifier specifies the data type of a single (scalar) value.
    * - ``str``
      - :py:class:`str`
      - ``string``
-     - String. If looks like a Python literal (e.g., ``"hello"``), it's parsed accordingly.
+     - String. If it looks like a Python literal (e.g., ``"hello"``), it is parsed accordingly.
 
 Examples:
 
@@ -129,8 +130,8 @@ Flag
 
 A flag is a boolean modifier that can be either on or off.
 
-Every flag is available as a attribute of the :class:`Field`.
-For example, we have a "required" flag registed, we can access ``Field.required``
+Every flag is available as an attribute of the :class:`Field`.
+For example, we have a "required" flag registered, and we can access ``Field.required``
 attribute.
 
 .. list-table::
@@ -154,8 +155,8 @@ By-Option
 
 A by-option is a key-value modifier with the syntax ``<name> by <value>``.
 
-Every by-option is available as a attribute of the :class:`Field`.
-For example, we have a "sep" flag registed, we can get the value of separator
+Every by-option is available as an attribute of the :class:`Field`.
+For example, we have a "sep" by-option registered, and we can get the separator
 from ``Field.sep`` attribute.
 
 Built-in by-options:
@@ -179,10 +180,10 @@ DSL                 Input     Result
 ``int, sep by ':'`` ``1:2:3`` :py:`[1, 2, 3]`
 =================== ========= ================
 
-Extending the DSL
+Extending the FDL
 =================
 
-You can extend the DSL by registering custom types, flags, and by-options
+You can extend the FDL by registering custom types, flags, and by-options
 through the :attr:`~sphinxnotes.render.Registry.data` attribute of
 :data:`sphinxnotes.render.REGISTRY`.
 
@@ -212,7 +213,7 @@ Adding Custom Flags
 -------------------
 
 Use :meth:`~sphinxnotes.render.data.Registry.add_flag` method of
-:data:`sphinxnotes.render.REGISTRY` to add a new type:
+:data:`sphinxnotes.render.REGISTRY` to add a new flag:
 
 >>> from sphinxnotes.render import REGISTRY
 >>> REGISTRY.data.add_flag('unique', default=False)

docs/index.rst

@@ -30,20 +30,17 @@ Introduction
 
 A framework to define, constrain, and render data in Sphinx documentation.
 
-.. seealso:: `sphinxnotes-any`__ and `sphinxnotes-data`__ 
-
-   __ https://sphinx.silverrainz.me/any/
-   __ https://sphinx.silverrainz.me/data/
-
 .. INTRODUCTION END
 
 Getting Started
 ===============
 
 .. ADDITIONAL CONTENT START
 
-This extension is not intended to be used directly by Sphinx user.
-It is for Sphinx extension developer, please refer to :doc:`dsl` and :doc:`api`.
+.. note::
+
+   This extension is not intended to be used directly by Sphinx users.
+   It is for Sphinx extension developers.
 
 .. ADDITIONAL CONTENT END
 
@@ -53,6 +50,7 @@ Contents
 .. toctree::
    :caption: Contents
 
+   usage
    dsl
    api
    changelog