Fix #3: Implement cloning of repos

* Implement a new "repo" subcommand:
  * `repo list` Lists all available repos which are already cloned
  * `repo dir`: Show the directory path for permanent repositories.
  * `repo clone`: Clone repos

* Implement a new Repo model that can be initialized from a URL
  or an abbreviated notation. It doesn't clone or interact with the
  filesystem, it just helps to "normalize" the (GitHub) repo URLs.

  Allow mapping of abbreviated schemes. Available are:
  gh (=GitHub), gl (=Gitlab), bb (=BitBucket), gt (=Gitea),
  cb (=Codeberg), ghe (=GitHub Enterprise)

* Integrate Repo into Deliverable.git
  The `repo_path` should be calculated inside Repo as this is
  the responsible class.

* Add tests for all subcommands and helper files

* Add changelog entry and update documentation

Author: tomschr

changelog.d/3.feature.rst

@@ -0,0 +1,13 @@
+Implement cloning of Git repositories
+
+All repos are "bare" clones, meaning they do not have a working directory.
+This was needed to avoid issues with branches.
+
+The internal logic is available through some CLI commands:
+
+* :command:`docbuild repo clone` - Clone a repository into the permanent storage.
+  With the help of the :class:`~docbuild.cli.models.repo.Repo` class,
+  it can handle different notations of repositories, such as HTTP URLs, SSH URLS, or abbreviated URLs (like ``gh://org/repo``).
+* :command:`docbuild repo dir` - Shows the directory path for permanent storage.
+  This is useful for debugging and manual operations.
+* :command:`docbuild repo list` - List all repositories in the permanent storage.

docs/source/reference/_autoapi/docbuild/cli/cmd_repo/cmd_clone/index.rst

@@ -0,0 +1,37 @@
+docbuild.cli.cmd_repo.cmd_clone
+===============================
+
+.. py:module:: docbuild.cli.cmd_repo.cmd_clone
+
+.. autoapi-nested-parse::
+
+   Clone repositories.
+
+   Pass any of the following URLs to clone:
+
+   
+   * HTTPS URLs like https://github.com/org/repo.git
+   * SSH URLS like [email protected]:org/repo.git
+   * Abbreviated URLs like 'org/repo'
+
+
+
+Functions
+---------
+
+.. autoapisummary::
+
+   docbuild.cli.cmd_repo.cmd_clone.clone
+
+
+Module Contents
+---------------
+
+.. py:function:: clone(ctx: click.Context, repos: tuple[str, Ellipsis]) -> None
+
+   Clone repositories into permanent directory.
+
+   :param repos: A tuple of repository selectors. If empty, all repos are cloned.
+   :param ctx: The Click context object.
+
+

docs/source/reference/_autoapi/docbuild/cli/cmd_repo/cmd_dir/index.rst

@@ -0,0 +1,32 @@
+docbuild.cli.cmd_repo.cmd_dir
+=============================
+
+.. py:module:: docbuild.cli.cmd_repo.cmd_dir
+
+.. autoapi-nested-parse::
+
+   Show the directory path for permanent repositories.
+
+
+
+Functions
+---------
+
+.. autoapisummary::
+
+   docbuild.cli.cmd_repo.cmd_dir.cmd_dir
+
+
+Module Contents
+---------------
+
+.. py:function:: cmd_dir(ctx: click.Context) -> None
+
+   Show the directory path for permanent repositories.
+
+   Outputs the path to the repository directory defined
+   in the environment configuration.
+
+   :param ctx: The Click context object.
+
+

docs/source/reference/_autoapi/docbuild/cli/cmd_repo/cmd_list/index.rst

@@ -0,0 +1,34 @@
+docbuild.cli.cmd_repo.cmd_list
+==============================
+
+.. py:module:: docbuild.cli.cmd_repo.cmd_list
+
+.. autoapi-nested-parse::
+
+   List the available permanent repositories.
+
+
+
+Functions
+---------
+
+.. autoapisummary::
+
+   docbuild.cli.cmd_repo.cmd_list.cmd_list
+
+
+Module Contents
+---------------
+
+.. py:function:: cmd_list(ctx: click.Context) -> None
+
+   List the available permanent repositories.
+
+   Outputs the directory names of all repositories defined in the
+   environment configuration.
+   If no repositories are defined, it outputs a message indicating that
+   no repositories are available.
+
+   :param ctx: The Click context object.
+
+

docs/source/reference/_autoapi/docbuild/cli/cmd_repo/index.rst

@@ -0,0 +1,74 @@
+docbuild.cli.cmd_repo
+=====================
+
+.. py:module:: docbuild.cli.cmd_repo
+
+.. autoapi-nested-parse::
+
+   Manage repositories.
+
+
+
+Submodules
+----------
+
+.. toctree::
+   :maxdepth: 1
+
+   /reference/_autoapi/docbuild/cli/cmd_repo/cmd_clone/index
+   /reference/_autoapi/docbuild/cli/cmd_repo/cmd_dir/index
+   /reference/_autoapi/docbuild/cli/cmd_repo/cmd_list/index
+   /reference/_autoapi/docbuild/cli/cmd_repo/process/index
+
+
+Functions
+---------
+
+.. autoapisummary::
+
+   docbuild.cli.cmd_repo.clone
+   docbuild.cli.cmd_repo.cmd_dir
+   docbuild.cli.cmd_repo.cmd_list
+   docbuild.cli.cmd_repo.repo
+
+
+Package Contents
+----------------
+
+.. py:function:: clone(ctx: click.Context, repos: tuple[str, Ellipsis]) -> None
+
+   Clone repositories into permanent directory.
+
+   :param repos: A tuple of repository selectors. If empty, all repos are cloned.
+   :param ctx: The Click context object.
+
+
+.. py:function:: cmd_dir(ctx: click.Context) -> None
+
+   Show the directory path for permanent repositories.
+
+   Outputs the path to the repository directory defined
+   in the environment configuration.
+
+   :param ctx: The Click context object.
+
+
+.. py:function:: cmd_list(ctx: click.Context) -> None
+
+   List the available permanent repositories.
+
+   Outputs the directory names of all repositories defined in the
+   environment configuration.
+   If no repositories are defined, it outputs a message indicating that
+   no repositories are available.
+
+   :param ctx: The Click context object.
+
+
+.. py:function:: repo(ctx: click.Context) -> None
+
+   Subcommand to validate XML configuration files.
+
+   :param ctx: The Click context object.
+
+

docs/source/reference/_autoapi/docbuild/cli/cmd_repo/process/index.rst

@@ -0,0 +1,42 @@
+docbuild.cli.cmd_repo.process
+=============================
+
+.. py:module:: docbuild.cli.cmd_repo.process
+
+.. autoapi-nested-parse::
+
+   Clone Git repositories from a stitchfile or a list of repository URLs.
+
+
+
+Functions
+---------
+
+.. autoapisummary::
+
+   docbuild.cli.cmd_repo.process.clone_repo
+   docbuild.cli.cmd_repo.process.process
+
+
+Module Contents
+---------------
+
+.. py:function:: clone_repo(repo: docbuild.models.repo.Repo, base_dir: pathlib.Path) -> bool
+   :async:
+
+
+   Clone a GitHub repository into the specified base directory.
+
+
+.. py:function:: process(context: docbuild.cli.context.DocBuildContext, repos: tuple[str, Ellipsis]) -> int
+   :async:
+
+
+   Process the cloning of repositories.
+
+   :param context: The DocBuildContext object containing configuration.
+   :param repos: A tuple of repository selectors. If empty, all repos are used.
+   :return: An integer exit code.
+   :raises ValueError: If configuration paths are missing.
+
+

docs/source/reference/_autoapi/docbuild/models/deliverable/Deliverable.rst

@@ -114,7 +114,7 @@ docbuild.models.deliverable.Deliverable
 
 
    .. py:property:: git
-      :type: str
+      :type: docbuild.models.repo.Repo
 
 
       Return the git repository.

docs/source/reference/_autoapi/docbuild/models/index.rst

@@ -21,6 +21,7 @@ Submodules
    /reference/_autoapi/docbuild/models/lifecycle/index
    /reference/_autoapi/docbuild/models/metadata/index
    /reference/_autoapi/docbuild/models/product/index
+   /reference/_autoapi/docbuild/models/repo/index
    /reference/_autoapi/docbuild/models/serverroles/index
 
 

docs/source/reference/_autoapi/docbuild/models/repo/Repo.rst

@@ -0,0 +1,76 @@
+docbuild.models.repo.Repo
+=========================
+
+.. py:class:: docbuild.models.repo.Repo(value: str)
+
+   A repository model that can be initialized from a URL or a short name.
+
+   This model can be compared directly with strings, which will check
+   against the repository's abbreviated name (e.g., 'org/repo').
+
+   Two Repo objects are considered equal if their derived names are the same,
+   regardless of the original URL (HTTPS vs. SSH).
+
+
+   .. py:attribute:: DEFAULT_HOST
+      :type:  ClassVar[str]
+      :value: 'https://github.com'
+
+
+      The default host to use when constructing a URL from a short name.
+
+
+
+   .. py:attribute:: url
+      :type:  str
+
+      The full URL of the repository.
+
+
+
+   .. py:attribute:: surl
+      :type:  str
+
+      The shortened URL version of the repository, for example gh://org/repo for
+      a GitHub repo.
+
+
+
+   .. py:attribute:: name
+      :type:  str
+
+      The abbreviated name of the repository (e.g., 'org/repo').
+
+
+
+   .. py:method:: __eq__(other: object) -> bool
+
+      Compare Repo with another Repo (by name) or a string (by name).
+
+
+
+   .. py:method:: __str__() -> str
+
+      Return the canonical URL of the repository.
+
+
+
+   .. py:method:: __hash__() -> int
+
+      Hash the Repo object based on its canonical derived name.
+
+
+
+   .. py:method:: __contains__(item: str) -> bool
+
+      Check if a string is part of the repository's abbreviated name.
+
+
+
+   .. py:property:: slug
+      :type: str
+
+
+      Return the slug name of the repository.
+
+

docs/source/reference/_autoapi/docbuild/models/repo/index.rst

@@ -0,0 +1,24 @@
+docbuild.models.repo
+====================
+
+.. py:module:: docbuild.models.repo
+
+.. autoapi-nested-parse::
+
+   A repository model that can be initialized from a URL or a short name.
+
+
+
+Classes
+-------
+
+.. toctree::
+   :hidden:
+
+   /reference/_autoapi/docbuild/models/repo/Repo
+
+.. autoapisummary::
+
+   docbuild.models.repo.Repo
+
+