Fix #4: Automate JSON generation

* Integrate subcommand `docbuild metadata` with the options:
  * `-E`, `--exitfirst`: Exit on first failed deliverable.
    Sometimes you want to stop when something bad happens.
  * `-S`, `--skip-repo-update`: Skip updating the (permanent) Git
     repositories before processing.
     When you need to re-run the script, in some cases you don't
     want to update the Git repo. Keeping it in the previous state
     is what this option does.
* Correctly implement updating Git bare repo using the command
  `git fetch origin +refs/heads/*:refs/heads/*`. It updates all branches.
* Create ManagedGitRepo class. Keeps track of all updated repositories
  and does update only once.
* Collects all JSON files and combines them into a single JSON file.

Author: tomschr

changelog.d/106.feature.rst

@@ -0,0 +1 @@
+Introduces the new :command:`docbuild metadata` to automate the process of generating and caching documentation metadata.

src/docbuild/cli/cmd_cli.py

@@ -9,7 +9,7 @@
 from rich.pretty import install
 from rich.traceback import install as install_traceback
 from pydantic import ValidationError
-from typing import Any, cast 
+from typing import Any, cast
 
 from ..__about__ import __version__
 from ..config.app import replace_placeholders
@@ -112,7 +112,6 @@ def cli(
     :param env_config: Filename to a environment's TOML config file.
     :param kwargs: Additional keyword arguments.
     """
-
     if ctx.invoked_subcommand is None:
         # If no subcommand is invoked, show the help message
         click.echo(10 * '-')
@@ -127,9 +126,9 @@ def cli(
     context.verbose = verbose
     context.dry_run = dry_run
     context.debug = debug
-    
+
     # --- PHASE 1: Load and Validate Application Config (and setup logging) ---
-    
+    #
     # 1. Load the raw application config dictionary
     (
         context.appconfigfiles,
@@ -162,7 +161,7 @@ def cli(
     setup_logging(cliverbosity=verbose, user_config={'logging': logging_config})
 
     # --- PHASE 2: Load Environment Config, Validate, and Acquire Lock ---
-    
+    #
     # 1. Load raw Environment Config
     (
         context.envconfigfiles,
@@ -175,10 +174,10 @@ def cli(
         DEFAULT_ENV_CONFIG_FILENAME,
         DEFAULT_ENV_CONFIG,
     )
-    
+
     # Explicitly cast the raw_envconfig type to silence Pylance
     raw_envconfig = cast(dict[str, Any], raw_envconfig)
-    
+
     # 2. VALIDATE the raw environment config dictionary using Pydantic
     try:
         # Pydantic validation handles placeholder replacement via @model_validator
@@ -191,14 +190,14 @@ def cli(
              context.envconfigfiles, e
         )
         ctx.exit(1)
-    
+
     env_config_path = context.envconfigfiles[0] if context.envconfigfiles else None
-    
+
     # --- CONCURRENCY CONTROL: Use explicit __enter__ and cleanup registration ---
     if env_config_path:
         # 1. Instantiate the lock object
         ctx.obj.env_lock = PidFileLock(resource_path=env_config_path)
-        
+
         try:
             # 2. Acquire the lock by explicitly calling the __enter__ method.
             ctx.obj.env_lock.__enter__()
@@ -212,16 +211,16 @@ def cli(
             # Handles critical errors
             log.error("Failed to set up environment lock: %s", e)
             ctx.exit(1)
-        
+
         # 3. Register the lock's __exit__ method to be called when the context terminates.
         # We use a lambda to supply the three mandatory positional arguments (None)
         # expected by __exit__, satisfying the click.call_on_close requirement.
         ctx.call_on_close(lambda: ctx.obj.env_lock.__exit__(None, None, None))
-    
+
 # Add subcommand
 cli.add_command(build)
 cli.add_command(c14n)
 cli.add_command(config)
 cli.add_command(repo)
 cli.add_command(metadata)
-cli.add_command(validate)
+cli.add_command(validate)

src/docbuild/cli/cmd_metadata/__init__.py

@@ -13,7 +13,8 @@
 from .metaprocess import process
 
 # Set up rich consoles for output
-console_out = Console()
+stdout = Console()
+console_err = Console(stderr=True, style='red')
 
 
 @click.command(help=__doc__)
@@ -22,20 +23,32 @@
     nargs=-1,
     callback=validate_doctypes,
 )
+@click.option(
+    '-E', '--exitfirst',
+    is_flag=True,
+    default=False,
+    show_default=True,
+    help='Exit on first failed deliverable.',
+)
+@click.option(
+    '-S', '--skip-repo-update',
+    is_flag=True,
+    default=False,
+    show_default=True,
+    help='Skip updating git repositories before processing.',
+)
 @click.pass_context
 def metadata(
     ctx: click.Context,
     doctypes: tuple[Doctype],
+    exitfirst: bool,
+    skip_repo_update: bool,
 ) -> None:
     """Subcommand to create metadata files.
 
     :param ctx: The Click context object.
     """
     context: DocBuildContext = ctx.obj
-    if context.envconfig is None:
-        # log.critical('No envconfig found in context.')
-        raise ValueError('No envconfig found in context.')
-
     timer = make_timer('metadata')
     result = 1  # Default exit code for interruption or error
 
@@ -44,9 +57,12 @@ def metadata(
     t = None
     try:
         with timer() as t:
-            result = asyncio.run(process(context, doctypes))
+            result = asyncio.run(
+                process(context, doctypes,
+                        exitfirst=exitfirst, skip_repo_update=skip_repo_update)
+            )
     finally:
         if t and not math.isnan(t.elapsed):
-            console_out.print(f'Elapsed time {t.elapsed:0.2f}s')
+            stdout.print(f'Elapsed time {t.elapsed:0.2f}s')
 
     ctx.exit(result)