From 71703ca50e53699883d418d9224949f8eb90c85e Mon Sep 17 00:00:00 2001 From: Tom Schraitle Date: Thu, 30 Apr 2026 14:54:02 +0200 Subject: [PATCH] Fix problems when building the doc --- .../_autoapi/docbuild/cli/cmd_cli/index.rst | 19 +++++++++++ .../cli/cmd_config/application/index.rst | 29 ---------------- .../cli/cmd_config/environment/index.rst | 29 ---------------- .../docbuild/cli/cmd_config/index.rst | 8 ++--- .../docbuild/cli/cmd_config/list/index.rst | 33 +++++++++++++++++++ .../cli/cmd_config/validate/index.rst | 31 +++++++++++++++++ .../config/app/PlaceholderResolver.rst | 7 ++++ .../config/app/PlaceholderSyntaxError.rst | 13 ++++++++ .../_autoapi/docbuild/config/app/index.rst | 3 ++ .../_autoapi/docbuild/utils/errors/index.rst | 10 ++++++ .../_autoapi/docbuild/utils/flatten/index.rst | 31 +++++++++++++++++ .../_autoapi/docbuild/utils/index.rst | 1 + docs/source/user/config/application.rst | 25 -------------- docs/source/user/config/environment.rst | 25 -------------- 14 files changed, 152 insertions(+), 112 deletions(-) delete mode 100644 docs/source/reference/_autoapi/docbuild/cli/cmd_config/application/index.rst delete mode 100644 docs/source/reference/_autoapi/docbuild/cli/cmd_config/environment/index.rst create mode 100644 docs/source/reference/_autoapi/docbuild/cli/cmd_config/list/index.rst create mode 100644 docs/source/reference/_autoapi/docbuild/cli/cmd_config/validate/index.rst create mode 100644 docs/source/reference/_autoapi/docbuild/config/app/PlaceholderSyntaxError.rst create mode 100644 docs/source/reference/_autoapi/docbuild/utils/flatten/index.rst delete mode 100644 docs/source/user/config/application.rst delete mode 100644 docs/source/user/config/environment.rst diff --git a/docs/source/reference/_autoapi/docbuild/cli/cmd_cli/index.rst b/docs/source/reference/_autoapi/docbuild/cli/cmd_cli/index.rst index 5a9297a9..01e263c7 100644 --- a/docs/source/reference/_autoapi/docbuild/cli/cmd_cli/index.rst +++ b/docs/source/reference/_autoapi/docbuild/cli/cmd_cli/index.rst @@ -15,6 +15,8 @@ Functions .. autoapisummary:: docbuild.cli.cmd_cli.handle_validation_error + docbuild.cli.cmd_cli.load_app_config + docbuild.cli.cmd_cli.load_env_config docbuild.cli.cmd_cli.cli @@ -37,6 +39,23 @@ Module Contents status code after handling the error. +.. py:function:: load_app_config(ctx: click.Context, app_config: pathlib.Path, max_workers: str | None) -> None + + Load and validate Application configuration. + + :param ctx: The Click context object. The result will be added to ``ctx.obj.appconfig``. + :param app_config: The path to the application config file provided via CLI. + :param max_workers: The max_workers value from CLI options. + + +.. py:function:: load_env_config(ctx: click.Context, env_config: pathlib.Path) -> None + + Load and validate Environment configuration. + + :param ctx: The Click context object. The result will be added to ``ctx.obj.envconfig``. + :param env_config: The path to the environment config file provided via CLI. + + .. py:function:: cli(ctx: click.Context, verbose: int, dry_run: bool, debug: bool, app_config: pathlib.Path, env_config: pathlib.Path, max_workers: str | None, **kwargs: dict) -> None Acts as a main entry point for CLI tool. diff --git a/docs/source/reference/_autoapi/docbuild/cli/cmd_config/application/index.rst b/docs/source/reference/_autoapi/docbuild/cli/cmd_config/application/index.rst deleted file mode 100644 index e2632084..00000000 --- a/docs/source/reference/_autoapi/docbuild/cli/cmd_config/application/index.rst +++ /dev/null @@ -1,29 +0,0 @@ -docbuild.cli.cmd_config.application -=================================== - -.. py:module:: docbuild.cli.cmd_config.application - -.. autoapi-nested-parse:: - - CLI interface to show the configuration of the application files. - - - -Functions ---------- - -.. autoapisummary:: - - docbuild.cli.cmd_config.application.app - - -Module Contents ---------------- - -.. py:function:: app(ctx: click.Context) -> None - - Subcommand to show the application's configuration. - - :param ctx: The Click context object. - - diff --git a/docs/source/reference/_autoapi/docbuild/cli/cmd_config/environment/index.rst b/docs/source/reference/_autoapi/docbuild/cli/cmd_config/environment/index.rst deleted file mode 100644 index 6f332562..00000000 --- a/docs/source/reference/_autoapi/docbuild/cli/cmd_config/environment/index.rst +++ /dev/null @@ -1,29 +0,0 @@ -docbuild.cli.cmd_config.environment -=================================== - -.. py:module:: docbuild.cli.cmd_config.environment - -.. autoapi-nested-parse:: - - CLI interface to shows the configuration of the environment files. - - - -Functions ---------- - -.. autoapisummary:: - - docbuild.cli.cmd_config.environment.env - - -Module Contents ---------------- - -.. py:function:: env(ctx: click.Context) -> None - - Subcommand to show the ENV configuration. - - :param ctx: The Click context object. - - diff --git a/docs/source/reference/_autoapi/docbuild/cli/cmd_config/index.rst b/docs/source/reference/_autoapi/docbuild/cli/cmd_config/index.rst index bfb878ec..efe7d137 100644 --- a/docs/source/reference/_autoapi/docbuild/cli/cmd_config/index.rst +++ b/docs/source/reference/_autoapi/docbuild/cli/cmd_config/index.rst @@ -5,7 +5,7 @@ docbuild.cli.cmd_config .. autoapi-nested-parse:: - CLI interface to shows config files how docbuild sees it. + CLI interface to manage and view configuration. @@ -15,8 +15,8 @@ Submodules .. toctree:: :maxdepth: 1 - /reference/_autoapi/docbuild/cli/cmd_config/application/index - /reference/_autoapi/docbuild/cli/cmd_config/environment/index + /reference/_autoapi/docbuild/cli/cmd_config/list/index + /reference/_autoapi/docbuild/cli/cmd_config/validate/index Functions @@ -32,6 +32,6 @@ Package Contents .. py:function:: config(ctx: click.Context) -> None - Subcommand to show the configuration files and their content. + Subcommand to manage the configuration files and their content. diff --git a/docs/source/reference/_autoapi/docbuild/cli/cmd_config/list/index.rst b/docs/source/reference/_autoapi/docbuild/cli/cmd_config/list/index.rst new file mode 100644 index 00000000..2bd8f94c --- /dev/null +++ b/docs/source/reference/_autoapi/docbuild/cli/cmd_config/list/index.rst @@ -0,0 +1,33 @@ +docbuild.cli.cmd_config.list +============================ + +.. py:module:: docbuild.cli.cmd_config.list + +.. autoapi-nested-parse:: + + CLI interface to list the configuration. + + + +Functions +--------- + +.. autoapisummary:: + + docbuild.cli.cmd_config.list.print_section + docbuild.cli.cmd_config.list.list_config + + +Module Contents +--------------- + +.. py:function:: print_section(title: str, data: dict[str, Any], prefix: str, flat: bool, color: str) -> None + + Print a configuration section in either flat or JSON format. + + +.. py:function:: list_config(ctx: click.Context, app: bool, env: bool, flat: bool) -> None + + List the configuration as JSON or flat text. + + diff --git a/docs/source/reference/_autoapi/docbuild/cli/cmd_config/validate/index.rst b/docs/source/reference/_autoapi/docbuild/cli/cmd_config/validate/index.rst new file mode 100644 index 00000000..894ffd3d --- /dev/null +++ b/docs/source/reference/_autoapi/docbuild/cli/cmd_config/validate/index.rst @@ -0,0 +1,31 @@ +docbuild.cli.cmd_config.validate +================================ + +.. py:module:: docbuild.cli.cmd_config.validate + +.. autoapi-nested-parse:: + + CLI interface to validate the configuration files. + + + +Functions +--------- + +.. autoapisummary:: + + docbuild.cli.cmd_config.validate.validate + + +Module Contents +--------------- + +.. py:function:: validate(ctx: click.Context) -> None + + Validate TOML configuration files. + + This checks the syntax and schema of application and environment files. + + :param ctx: The Click context object, which should already have loaded configurations. + + diff --git a/docs/source/reference/_autoapi/docbuild/config/app/PlaceholderResolver.rst b/docs/source/reference/_autoapi/docbuild/config/app/PlaceholderResolver.rst index b9ed29f4..d327ec85 100644 --- a/docs/source/reference/_autoapi/docbuild/config/app/PlaceholderResolver.rst +++ b/docs/source/reference/_autoapi/docbuild/config/app/PlaceholderResolver.rst @@ -14,6 +14,12 @@ docbuild.config.app.PlaceholderResolver + .. py:method:: validate_brace_syntax(text: str, original_text: str) -> None + + Validate that curly braces are balanced and properly ordered. + + + .. py:method:: get_container_name() -> str Public accessor for the current container/key name. @@ -31,5 +37,6 @@ docbuild.config.app.PlaceholderResolver :return: The configuration with all placeholders resolved. :raises PlaceholderResolutionError: If a placeholder cannot be resolved. :raises CircularReferenceError: If a circular reference is detected. + :raises PlaceholderSyntaxError: If a placeholder has invalid syntax. diff --git a/docs/source/reference/_autoapi/docbuild/config/app/PlaceholderSyntaxError.rst b/docs/source/reference/_autoapi/docbuild/config/app/PlaceholderSyntaxError.rst new file mode 100644 index 00000000..e6bc6c1a --- /dev/null +++ b/docs/source/reference/_autoapi/docbuild/config/app/PlaceholderSyntaxError.rst @@ -0,0 +1,13 @@ +docbuild.config.app.PlaceholderSyntaxError +========================================== + +.. py:exception:: docbuild.config.app.PlaceholderSyntaxError + + Bases: :py:obj:`ValueError` + + .. autoapi-inheritance-diagram:: docbuild.config.app.PlaceholderSyntaxError + :parts: 1 + + + Exception raised when a placeholder has invalid syntax. + diff --git a/docs/source/reference/_autoapi/docbuild/config/app/index.rst b/docs/source/reference/_autoapi/docbuild/config/app/index.rst index 61ec6e85..a9e60162 100644 --- a/docs/source/reference/_autoapi/docbuild/config/app/index.rst +++ b/docs/source/reference/_autoapi/docbuild/config/app/index.rst @@ -26,11 +26,13 @@ Exceptions /reference/_autoapi/docbuild/config/app/PlaceholderResolutionError /reference/_autoapi/docbuild/config/app/CircularReferenceError + /reference/_autoapi/docbuild/config/app/PlaceholderSyntaxError .. autoapisummary:: docbuild.config.app.PlaceholderResolutionError docbuild.config.app.CircularReferenceError + docbuild.config.app.PlaceholderSyntaxError Classes @@ -85,5 +87,6 @@ Module Contents :return: A new dictionary with placeholders replaced. :raises PlaceholderResolutionError: If a placeholder cannot be resolved. :raises CircularReferenceError: If a circular reference is detected. + :raises PlaceholderSyntaxError: If a placeholder has invalid syntax. diff --git a/docs/source/reference/_autoapi/docbuild/utils/errors/index.rst b/docs/source/reference/_autoapi/docbuild/utils/errors/index.rst index 1123ab3c..8311fe35 100644 --- a/docs/source/reference/_autoapi/docbuild/utils/errors/index.rst +++ b/docs/source/reference/_autoapi/docbuild/utils/errors/index.rst @@ -15,6 +15,7 @@ Functions .. autoapisummary:: docbuild.utils.errors.format_pydantic_error + docbuild.utils.errors.format_toml_error Module Contents @@ -31,3 +32,12 @@ Module Contents :param console: Optional Rich console object. If None, creates a stderr console. +.. py:function:: format_toml_error(error: tomllib.TOMLDecodeError, config_file: str, console: rich.console.Console | None = None) -> None + + Format TOML syntax errors using Rich. + + :param error: The caught TOMLDecodeError object. + :param config_file: The name/path of the config file with the syntax error. + :param console: Optional Rich console object. + + diff --git a/docs/source/reference/_autoapi/docbuild/utils/flatten/index.rst b/docs/source/reference/_autoapi/docbuild/utils/flatten/index.rst new file mode 100644 index 00000000..659497fb --- /dev/null +++ b/docs/source/reference/_autoapi/docbuild/utils/flatten/index.rst @@ -0,0 +1,31 @@ +docbuild.utils.flatten +====================== + +.. py:module:: docbuild.utils.flatten + +.. autoapi-nested-parse:: + + Utility to flatten nested dictionaries into dotted keys. + + + +Functions +--------- + +.. autoapisummary:: + + docbuild.utils.flatten.flatten_dict + + +Module Contents +--------------- + +.. py:function:: flatten_dict(d: dict[str, Any], prefix: str = '') -> collections.abc.Generator[tuple[str, Any], None, None] + + Recursively flatten a nested dictionary into dotted keys. + + :param d: The dictionary to flatten. + :param prefix: The current key prefix (used for recursion). + :yields: Tuples of (dotted_key, value). + + diff --git a/docs/source/reference/_autoapi/docbuild/utils/index.rst b/docs/source/reference/_autoapi/docbuild/utils/index.rst index 145f1496..b8676dca 100644 --- a/docs/source/reference/_autoapi/docbuild/utils/index.rst +++ b/docs/source/reference/_autoapi/docbuild/utils/index.rst @@ -21,6 +21,7 @@ Submodules /reference/_autoapi/docbuild/utils/decorators/index /reference/_autoapi/docbuild/utils/doc/index /reference/_autoapi/docbuild/utils/errors/index + /reference/_autoapi/docbuild/utils/flatten/index /reference/_autoapi/docbuild/utils/git/index /reference/_autoapi/docbuild/utils/merge/index /reference/_autoapi/docbuild/utils/paths/index diff --git a/docs/source/user/config/application.rst b/docs/source/user/config/application.rst deleted file mode 100644 index 023e3f3d..00000000 --- a/docs/source/user/config/application.rst +++ /dev/null @@ -1,25 +0,0 @@ -Showing App's Configuration -=========================== - -Application configuration files ("app config") affects the behavior of the docbuild tool itself, such as how it processes documents, logging, handles errors, etc. - -The tool can read these configuration files in different locations in the following order: - -* In the system configuration directory, typically located at ``/etc/docbuild/`` (lowest priority). -* In the user configuration directory, typically located at ``~/.config/docbuild/``. -* In the current working directory, where the docbuild tool is executed, at ``.`` (highest priority). - -In each of these location, the tool will look for configuration files named :file:`.config.toml` or :file:`config.toml`. Additionally, the tool will -merge the configuration from these files. Higher priority files will override the settings of lower priority files. - -If you want to override the default search strategy, use the ``--app-config`` option to specify a custom configuration file path. - -.. code-block:: shell-session - :caption: Showing configuration files - - docbuild config app - # Application config files '/home/tux/repos/GH/opensuse/docbuild/.config.toml' - [ ... content ...] - -In the previous example, there is a :file:`.config.toml` file in the -current project's directory. \ No newline at end of file diff --git a/docs/source/user/config/environment.rst b/docs/source/user/config/environment.rst deleted file mode 100644 index df9d41ba..00000000 --- a/docs/source/user/config/environment.rst +++ /dev/null @@ -1,25 +0,0 @@ -.. _config-show-env: - -Showing Env's Configuration -=========================== - -Environment configuration files ("env config") is specific to the environment in which the docbuild tool operates, such as paths to source files, output directories, and other environment-specific settings. - -The tool looks for the configuration :file:`env.production.toml` in the current working directory. - -If you want to override the default, use the ``--env-config`` option to specify a custom configuration file path. - -.. code-block:: shell-session - :caption: Showing env configuration content - - docbuild --env-config env.develop.toml config env - # ENV Config file '/home/tux/repos/GH/opensuse/docbuild/env.production.toml' - [ ... content ...] - -In the previous example, there is a :file:`env.production.toml` file in the -current project's directory. - -.. note:: - - An example of an environment configuration file is provided in this repo - in the :gh_path:`etc/docbuild/env.example.toml` directory.