Fix problems when building the doc (#245)

Author: tomschr

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.

docs/source/reference/_autoapi/docbuild/cli/cmd_config/application/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.
 
 

docs/source/reference/_autoapi/docbuild/cli/cmd_config/environment/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.
+
+

docs/source/reference/_autoapi/docbuild/cli/cmd_config/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.
+
+

docs/source/reference/_autoapi/docbuild/cli/cmd_config/list/index.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.
 
 

docs/source/reference/_autoapi/docbuild/cli/cmd_config/validate/index.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.
+

docs/source/reference/_autoapi/docbuild/config/app/PlaceholderResolver.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.
 
 

docs/source/reference/_autoapi/docbuild/config/app/PlaceholderSyntaxError.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.
+
+