docs: Fix typos and grammar

Co-authored-by: Codex <codex@openai.com>

Author: SilverRainZ

docs/api.rst

@@ -6,20 +6,20 @@ The Render Pipeline
 ===================
 
 The pipeline defines how nodes carrying data are generated and when they are
-rendered to part of the document.
+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:
 
-   - :ref:`context`, the dynamic content of Jinja template
+   - :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)
 
-2. Render: ``pending_node`` node will be rendered at appropriate
+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`.
 
@@ -33,27 +33,28 @@ Node
 Context
 -------
 
-Context refers dynamic content of Jinja template. It can be:
+Context refers to the dynamic content of a Jinja template. It can be:
 
 :py:class:`~sphinxnotes.render.ResolvedContext`:
-  Our dedicated data types (:py:class:`sphinxnotes.render.ParsedData`) , or any
+  Our dedicated data type (:py:class:`sphinxnotes.render.ParsedData`), or any
   Python ``dict``.
 
 :py:class:`~sphinxnotes.render.PendingContext`:
-   Context no yet available. e.g. Context contains
-   :py:class:`un-parsed data <sphinxnotes.render.RawData>`),
-   remote data, and etc.
+   Context that is not yet available. For example, it may contain
+   :py:class:`unparsed data <sphinxnotes.render.RawData>`,
+   remote data, and more.
 
-   PendingContext can be resolved to :py:class:`~sphinxnotes.render.ResolvedContext`.
-   by calling the :py:class:`~sphinxnotes.render.PendingContext.resolve` method.
+   :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`` Implementions
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+``PendingContext`` Implementations
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 .. autoclass:: sphinxnotes.render.UnparsedData
    :show-inheritance:
@@ -141,8 +142,8 @@ Data, Field and Schema
 Registry
 ========
 
-Developer can extending the function of this extentison (For example, support
-more data types, add new extra context) by adding new item to
+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

docs/dsl.rst

@@ -8,9 +8,9 @@ Field Description Language
    :language: Python
 
 
-The Field Description Language is a Domain Specific Language (DSL) that used to
+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`\ s separated by commas (``,``).
+one or more :term:`modifier` entries separated by commas (``,``).
 
 Syntax
 ======
@@ -39,8 +39,8 @@ Syntax
 Python API
 ==========
 
-User can create a :class:`sphinxnotes.render.Field` from FDL and use it to parse
-string to :type:`sphinxnotes.render.Value`:
+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')
@@ -74,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:
 
@@ -130,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::
@@ -155,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:
@@ -213,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

@@ -39,8 +39,8 @@ Getting Started
 
 .. note::
 
-   This extension is not intended to be used directly by Sphinx user.
-   It is for Sphinx extension developer.
+   This extension is not intended to be used directly by Sphinx users.
+   It is for Sphinx extension developers.
 
 .. ADDITIONAL CONTENT END
 

docs/usage.rst

@@ -6,7 +6,7 @@ Usage
 
    Before reading this documentation, please refer to
    :external+sphinx:doc:`development/tutorials/extending_syntax`.
-   see how to extends :py:class:`SphinxDirective` and :py:class:`SphinxRole`.
+   See how to extend :py:class:`SphinxDirective` and :py:class:`SphinxRole`.
 
 Create a Sphinx documentation with the following ``conf.py``:
 

src/sphinxnotes/render/__init__.py

@@ -47,7 +47,7 @@
     from sphinx.application import Sphinx
 
 
-"""Python API for other Sphinx extesions."""
+"""Python API for other Sphinx extensions."""
 __all__ = [
     'Registry',
     'PlainValue',
@@ -76,7 +76,7 @@
 
 
 class Registry:
-    """The global, all-in-one registry for user."""
+    """The global, all-in-one registry for users."""
 
     @property
     def data(self) -> DataRegistry:

src/sphinxnotes/render/ctx.py

@@ -1,5 +1,5 @@
 """
-This module wraps the :py:mod:`sphinxnote.render.data` module into context
+This module wraps the :py:mod:`sphinxnotes.render.data` module into context
 suitable for use with Jinja templates.
 """
 
@@ -12,12 +12,12 @@
 from .utils import Unpicklable
 
 type ResolvedContext = ParsedData | dict[str, Any]
-"""The context is """
+"""Resolved context types used by template rendering."""
 
 
 @dataclass
 class PendingContextRef:
-    """A abstract class that references to :class:`PendingCtx`."""
+    """An abstract reference to :class:`PendingContext`."""
 
     ref: int
     chksum: int
@@ -27,7 +27,7 @@ def __hash__(self) -> int:
 
 
 class PendingContext(ABC, Unpicklable, Hashable):
-    """A abstract representation of context that is not currently available."""
+    """An abstract representation of context that is not currently available."""
 
     @abstractmethod
     def resolve(self) -> ResolvedContext:
@@ -39,13 +39,13 @@ def resolve(self) -> ResolvedContext:
 class PendingContextStorage:
     """Area for temporarily storing :py:class:`PendingContext`.
 
-    This class is indented to resolve the problem that:
+    This class is intended to solve the problem that:
 
-        Some of the PendingContext are :class:Unpicklable` and they can not be hold
+        Some :class:`PendingContext` objects are :class:`Unpicklable`, so they cannot be held
         by :class:`pending_node` (as ``pending_node`` will be pickled along with
         the docutils doctree)
 
-    This class maintains a mapping from :class:`PendingContextRef` -> :cls:`PendingContext`.
+    This class maintains a mapping from :class:`PendingContextRef` -> :class:`PendingContext`.
     ``pending_node`` owns the ``PendingContextRef``, and can retrieve the context
     by calling :py:meth:`retrieve`.
     """

src/sphinxnotes/render/ctxnodes.py

@@ -217,7 +217,7 @@ def unwrap_and_replace_self_inline(self, inliner: Report.Inliner) -> None:
         # Replace self with inline nodes.
         self.replace_self(ns)
 
-    """Hooks for procssing render intermediate products. """
+    """Hooks for processing render intermediate products."""
 
     type PendingContextHook = Callable[[pending_node, PendingContext], None]
     type ResolvedContextHook = Callable[[pending_node, ResolvedContext], None]

src/sphinxnotes/render/data.py

@@ -178,7 +178,7 @@ def add_type(
     def add_form(
         self, name: str, ctype: type, sep: str, aliases: list[str] = []
     ) -> None:
-        """Register an value form with its container type and separator for
+        """Register a value form with its container type and separator for
         :py:class:`Value`.
 
         :param name: The name for this form, available as a :term:`Form modifier`
@@ -270,8 +270,8 @@ def asdict(self) -> dict[str, Any]:
         """
         Convert Data to a dict for usage of Jinja2 context.
 
-        ``self.attrs`` will be automaticlly lifted to top-level context when
-        there is no key conflicts. For example:
+        ``self.attrs`` will be automatically lifted to top-level context when
+        there are no key conflicts. For example:
 
         - You can access ``Data.attrs['color']`` by "{{ color }}" instead
           of "{{ attrs.color }}".
@@ -293,7 +293,7 @@ class Field(Unpicklable):
     ctype: type | None = None
     #: Flags of field.
     flags: dict[str, Value] = dataclass_field(default_factory=dict)
-    #: The orginal DSL.
+    #: The original DSL.
     dsl: str | None = None
 
     # Type hints for builtin flags.

src/sphinxnotes/render/extractx.py

@@ -17,15 +17,14 @@
 
 
 class GlobalExtraContxt(ABC):
-    """Extra context availabled on any phase."""
+    """Extra context available in any phase."""
 
     @abstractmethod
     def generate(self) -> Any: ...
 
 
 class ParsePhaseExtraContext(ABC):
-    """Extra context generated during the :py:class:`~Phase.Parsing` or
-    :py:class:`~Phase.Parsing` phase."""
+    """Extra context generated during the :py:class:`~Phase.Parsing` phase."""
 
     @abstractmethod
     def generate(self, host: ParseHost) -> Any: ...
@@ -39,7 +38,7 @@ def generate(self, host: ResolveHost) -> Any: ...
 
 
 # =======================
-# Extra context registion
+# Extra context registration
 # =======================
 
 
@@ -72,32 +71,32 @@ def _name_dedup(self, name: str) -> None:
     def add_parsing_phase_context(
         self, name: str, ctxgen: ParsePhaseExtraContext
     ) -> None:
-        """Register a extra context for :py:class:`~Phase.Parsing` phase."""
+        """Register an extra context for the :py:class:`~Phase.Parsing` phase."""
         self._name_dedup(name)
         self.parsing['_' + name] = ctxgen
 
     def add_parsed_phase_context(
         self, name: str, ctxgen: ResolvePhaseExtraContext
     ) -> None:
-        """Register a extra context for :py:class:`~Phase.Parsed` phase."""
+        """Register an extra context for the :py:class:`~Phase.Parsed` phase."""
         self._name_dedup(name)
         self.parsed['_' + name] = ctxgen
 
     def add_post_transform_phase_context(
         self, name: str, ctxgen: ResolvePhaseExtraContext
     ) -> None:
-        """Register a extra context for :py:class:`~Phase.Resolving` phase."""
+        """Register an extra context for the :py:class:`~Phase.Resolving` phase."""
         self._name_dedup(name)
         self.post_transform['_' + name] = ctxgen
 
     def add_global_context(self, name: str, ctxgen: GlobalExtraContxt):
-        """Register a extra context for :py:class:`~Phase.Resolving` phase."""
+        """Register a global extra context available across phases."""
         self._name_dedup(name)
         self.global_['_' + name] = ctxgen
 
 
 # ===================================
-# Bulitin extra context implementions
+# Builtin extra context implementations
 # ===================================