From 46fad71eea1e46ca7f3590a44c59ac3c911e4b72 Mon Sep 17 00:00:00 2001 From: tanbro Date: Tue, 7 Jan 2025 20:42:52 +0800 Subject: [PATCH] docs(apidocs): remove yaml_include package documentation - Remove yaml_include package API documentation - Delete yaml_include.rst and related module files --- .gitignore | 6 +- .vscode/tasks.json | 69 +++++++++++++++++++++++ docs/README.rst | 33 +++++------ docs/apidocs/.gitignore | 2 + docs/apidocs/yaml_include.constructor.rst | 7 --- docs/apidocs/yaml_include.data.rst | 7 --- docs/apidocs/yaml_include.funcs.rst | 7 --- docs/apidocs/yaml_include.representer.rst | 7 --- docs/apidocs/yaml_include.rst | 10 ---- docs/index.rst | 2 +- src/yaml_include/constructor.py | 11 ++-- src/yaml_include/funcs.py | 12 +++- src/yaml_include/representer.py | 9 +-- 13 files changed, 109 insertions(+), 73 deletions(-) create mode 100644 .vscode/tasks.json create mode 100644 docs/apidocs/.gitignore delete mode 100644 docs/apidocs/yaml_include.constructor.rst delete mode 100644 docs/apidocs/yaml_include.data.rst delete mode 100644 docs/apidocs/yaml_include.funcs.rst delete mode 100644 docs/apidocs/yaml_include.representer.rst delete mode 100644 docs/apidocs/yaml_include.rst diff --git a/.gitignore b/.gitignore index 833bd26..081b55a 100644 --- a/.gitignore +++ b/.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. diff --git a/.vscode/tasks.json b/.vscode/tasks.json new file mode 100644 index 0000000..0168d11 --- /dev/null +++ b/.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" + ] + } + ] +} diff --git a/docs/README.rst b/docs/README.rst index 0333e0f..cd2c89f 100644 --- a/docs/README.rst +++ b/docs/README.rst @@ -4,44 +4,44 @@ README .. include:: ../README.md :parser: myst_parser.sphinx_ -How to build docs -================= +How to Build the Documentation +============================== -#. This documentation is made with `Sphinx `_, be sure to install it's dependencies: +#. The documentation is built using `Sphinx `_. + 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. @@ -49,11 +49,6 @@ then open http://localhost:8000/ in a web browser. .. 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:: diff --git a/docs/apidocs/.gitignore b/docs/apidocs/.gitignore new file mode 100644 index 0000000..d6b7ef3 --- /dev/null +++ b/docs/apidocs/.gitignore @@ -0,0 +1,2 @@ +* +!.gitignore diff --git a/docs/apidocs/yaml_include.constructor.rst b/docs/apidocs/yaml_include.constructor.rst deleted file mode 100644 index c5b89cf..0000000 --- a/docs/apidocs/yaml_include.constructor.rst +++ /dev/null @@ -1,7 +0,0 @@ -yaml\_include.constructor module -================================ - -.. automodule:: yaml_include.constructor - :members: - :undoc-members: - :show-inheritance: diff --git a/docs/apidocs/yaml_include.data.rst b/docs/apidocs/yaml_include.data.rst deleted file mode 100644 index 30b87fd..0000000 --- a/docs/apidocs/yaml_include.data.rst +++ /dev/null @@ -1,7 +0,0 @@ -yaml\_include.data module -========================= - -.. automodule:: yaml_include.data - :members: - :undoc-members: - :show-inheritance: diff --git a/docs/apidocs/yaml_include.funcs.rst b/docs/apidocs/yaml_include.funcs.rst deleted file mode 100644 index 387195a..0000000 --- a/docs/apidocs/yaml_include.funcs.rst +++ /dev/null @@ -1,7 +0,0 @@ -yaml\_include.funcs module -========================== - -.. automodule:: yaml_include.funcs - :members: - :undoc-members: - :show-inheritance: diff --git a/docs/apidocs/yaml_include.representer.rst b/docs/apidocs/yaml_include.representer.rst deleted file mode 100644 index e22b3af..0000000 --- a/docs/apidocs/yaml_include.representer.rst +++ /dev/null @@ -1,7 +0,0 @@ -yaml\_include.representer module -================================ - -.. automodule:: yaml_include.representer - :members: - :undoc-members: - :show-inheritance: diff --git a/docs/apidocs/yaml_include.rst b/docs/apidocs/yaml_include.rst deleted file mode 100644 index 4e7e4d2..0000000 --- a/docs/apidocs/yaml_include.rst +++ /dev/null @@ -1,10 +0,0 @@ -yaml\_include package -===================== - -.. toctree:: - :maxdepth: 4 - - yaml_include.constructor - yaml_include.data - yaml_include.funcs - yaml_include.representer diff --git a/docs/index.rst b/docs/index.rst index 47e335c..68f9ce2 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -52,7 +52,7 @@ Contents :caption: API Reference :titlesonly: - apidocs/yaml_include + apidocs/modules ------------------ Indices and tables diff --git a/src/yaml_include/constructor.py b/src/yaml_include/constructor.py index 92c29d7..b598c26 100644 --- a/src/yaml_include/constructor.py +++ b/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,6 +199,9 @@ 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: @@ -208,8 +209,8 @@ def managed_autoload(self, autoload: bool) -> Iterator[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): diff --git a/src/yaml_include/funcs.py b/src/yaml_include/funcs.py index df67a37..d27d418 100644 --- a/src/yaml_include/funcs.py +++ b/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) diff --git a/src/yaml_include/representer.py b/src/yaml_include/representer.py index 132fa95..52ad3cf 100644 --- a/src/yaml_include/representer.py +++ b/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