docs(apidocs): remove yaml_include package documentation

- Remove yaml_include package API documentation
- Delete yaml_include.rst and related module files

.gitignore

@@ -309,9 +309,9 @@ local.properties
 
 .vscode/*
 # !.vscode/settings.json
-# !.vscode/tasks.json
-# !.vscode/launch.json
-# !.vscode/extensions.json
+!.vscode/tasks.json
+!.vscode/launch.json
+!.vscode/extensions.json
 
 ## Ignore Visual Studio temporary files, build results, and
 ## files generated by popular Visual Studio add-ons.

.vscode/tasks.json

@@ -0,0 +1,69 @@
+{
+    // See https://go.microsoft.com/fwlink/?LinkId=733558
+    // for the documentation about the tasks.json format
+    "version": "2.0.0",
+    "tasks": [
+        {
+            "label": "build",
+            "type": "shell",
+            "command": "${command:python.interpreterPath} -m build",
+            "problemMatcher": [
+                "$python"
+            ],
+            "group": {
+                "kind": "build",
+                "isDefault": true
+            }
+        },
+        {
+            "label": "test",
+            "type": "shell",
+            "command": "${command:python.interpreterPath} -m unittest",
+            "problemMatcher": [
+                "$python"
+            ],
+            "group": {
+                "kind": "test",
+                "isDefault": true
+            }
+        },
+        {
+            "label": "docs: build",
+            "type": "shell",
+            "command": "${command:python.interpreterPath} -m sphinx -j auto -d _build/doctrees . _build/html",
+            "options": {
+                "cwd": "${workspaceFolder}/docs"
+            },
+            "problemMatcher": [
+                "$python"
+            ]
+        },
+        {
+            "label": "docs: serve",
+            "type": "shell",
+            "command": "${command:python.interpreterPath} -m http.server -d _build/html",
+            "options": {
+                "cwd": "${workspaceFolder}/docs"
+            },
+            "problemMatcher": [
+                "$python"
+            ]
+        },
+        {
+            "label": "lint",
+            "type": "shell",
+            "command": "${command:python.interpreterPath} -m ruff check --fix && ${command:python.interpreterPath} -m ruff format",
+            "problemMatcher": [
+                "$python"
+            ]
+        },
+        {
+            "label": "static type check",
+            "type": "shell",
+            "command": "${command:python.interpreterPath} -m mypy",
+            "problemMatcher": [
+                "$python"
+            ]
+        }
+    ]
+}

docs/README.rst

@@ -4,56 +4,51 @@ README
 .. include:: ../README.md
    :parser: myst_parser.sphinx_
 
-How to build docs
-=================
+How to Build the Documentation
+==============================
 
-#. This documentation is made with `Sphinx <https://www.sphinx-doc.org/>`_, be sure to install it's dependencies:
+#. The documentation is built using `Sphinx <https://www.sphinx-doc.org/>`_.
+   We need to install the package and its testing requirements:
 
    .. code:: sh
 
-      pip install -r docs/requirements.txt
+      pip install -e . -r docs/requirements.txt
 
-   Ignore this step if requirements already installed.
-
-#. (*Optional*) Re-generate API-Docs, if source tree changed:
+#. Generate API documentation.
+   If the source tree has changed, you may clear the `docs/apidocs` directory and regenerate the API documentation:
 
    .. code:: sh
 
-      sphinx-apidoc -o docs/apidocs -eMTf src
+      sphinx-apidoc -o docs/apidocs -f -e -H APIs src
 
 #. Build HTML documentation:
 
-   * Make tool:
+   * Using the Make tool (for Unix/Linux/macOS):
 
       .. code:: sh
 
          make -C docs html
 
-   * Windows:
+   * On Windows:
 
       .. code:: bat
 
          docs\make html
 
-The built-out static web site is at ``docs/_build/html``, we can serve it:
+The built static website is located at ``docs/_build/html``. You can serve it with a simple HTTP server:
 
 .. code:: sh
 
-   python -m http.server -d docs/_build/html
+   python -m http.server --directory docs/_build/html
 
-then open http://localhost:8000/ in a web browser.
+Then open http://localhost:8000/ in a web browser.
 
 .. tip::
    Try another port if ``8000`` is already in use.
    For example, to serve on port ``8080``:
 
    .. code:: sh
 
-      python -m http.server -d docs/_build/html 8080
+      python -m http.server --directory docs/_build/html 8080
 
    .. seealso:: Python ``stdlib``'s :mod:`http.server`
-
-.. tip::
-   If want to build PDF, use ``make rinoh`` instead.
-
-   .. seealso:: <https://www.sphinx-doc.org/en/master/usage/builders/index.html#sphinx.builders.latex.LaTeXBuilder>

docs/apidocs/.gitignore

@@ -0,0 +1,2 @@
+*
+!.gitignore

docs/index.rst

@@ -52,7 +52,7 @@ Contents
    :caption: API Reference
    :titlesonly:
 
-   apidocs/yaml_include
+   apidocs/modules
 
 ------------------
 Indices and tables

src/yaml_include/constructor.py

@@ -30,8 +30,6 @@
 from .data import Data
 
 if TYPE_CHECKING:  # pragma: no cover
-    from yaml import Node
-    from yaml.constructor import _Scalar  # type: ignore[attr-defined]
     from yaml.cyaml import _CLoader
     from yaml.loader import _Loader
     from yaml.reader import _ReadStream
@@ -168,7 +166,7 @@ def my_loader(urlpath, file, Loader):
                 - Neither a wildcard nor a scheme is present in the include statement (e.g., ``!inc foo/baz.yml``).
                 - Either a wildcard or a scheme is present in the include statement (e.g., ``!inc http://host/foo/*.yml``).
             - Each file name returned by :meth:`fsspec.spec.AbstractFileSystem.glob`,
-            if a wildcard is present but no scheme in the include statement (e.g., ``!inc foobar/**/*.yml``).
+              if a wildcard is present but no scheme in the include statement (e.g., ``!inc foobar/**/*.yml``).
 
         file (bytes | str | SupportsRead[bytes | str]):
             The object returned by :func:`fsspec.open` or a member of the list returned by :func:`fsspec.open_files`.
@@ -201,15 +199,18 @@ def managed_autoload(self, autoload: bool) -> Iterator[Self]:
 
         Args:
             autoload: The temporary value to assign to :attr:`autoload` within the ``with`` statement.
+
+        Yields:
+            The current instance of :class:`.Constructor`.
         """
         saved, self.autoload = self.autoload, bool(autoload)
         try:
             yield self
         finally:
             self.autoload = saved
 
-    def __call__(self, loader: Union[_Loader, _CLoader], node: Node) -> Union[Data, Any]:
-        val: Union[_Scalar, Sequence, Mapping]
+    def __call__(self, loader: Union[_Loader, _CLoader], node: yaml.Node) -> Union[Data, Any]:
+        val: Union[Sequence, Mapping, str]
         if is_yaml_scalar_node(node):
             val = loader.construct_scalar(node)
             if isinstance(val, str):

src/yaml_include/funcs.py

@@ -31,10 +31,17 @@ def load(
         loader_type: The type of PyYAML Loader to use for parsing strings in included files.
         constructor: The :class:`.Constructor` instance used to find, open, and read included files.
         inplace: Whether to perform in-place replacement for each :class:`.Data` instance in ``obj``.
-        nested: Whether to recursively parse and load lower-level include statements within :class:`.Data` instances.
+
+        nested: Whether to recursively parse and load "include statements" inside :class:`.Data` instances.
+
+            Note:
+                The parameter is used for "include within include" scenarios, allowing nested includes.
 
     Returns:
         The fully parsed object with all included files loaded and processed.
+
+    Warning:
+        The function is **recursive** and can lead to a **stack overflow** if the ``obj`` is too deeply nested.
     """
     if isinstance(obj, Data):
         d = constructor.load(loader_type, obj)
@@ -70,6 +77,9 @@ def lazy_load(
 
     * It returns a :term:`generator` that yields each :class:`.Data` instance found within ``obj``.
     * It performs in-place parsing and replacement, but does not return the fully parsed object.
+
+    Yields:
+        Object parsed from the :class:`.Data` instances as one is encountered.
     """
     if isinstance(obj, Data):
         d = constructor.load(loader_type, obj)

src/yaml_include/representer.py

@@ -1,11 +1,8 @@
-from __future__ import annotations
-
 from dataclasses import dataclass
 from itertools import chain
-from typing import TYPE_CHECKING
 
-if TYPE_CHECKING:  # pragma: no cover
-    from yaml import Dumper, Node
+from yaml import Node
+from yaml.representer import BaseRepresenter
 
 from .data import Data
 
@@ -36,7 +33,7 @@ class Representer:
       as :func:`yaml.add_representer` will automatically add the symbol.
     """
 
-    def __call__(self, dumper: Dumper, data: Data) -> Node:
+    def __call__(self, dumper: BaseRepresenter, data: Data) -> Node:
         if not isinstance(data, Data):  # pragma: no cover
             raise TypeError(f"{type(data)}")
         tag = "!" + self.tag