Add repository finding mechanism similar to PATH

Author: pedro-psb

src/pulp_docs/cli.py

@@ -1,7 +1,12 @@
 import click
 
 from mkdocs.__main__ import cli as mkdocs_cli
-from pulp_docs.context import ctx_blog, ctx_docstrings, ctx_draft
+from pulp_docs.context import (
+    ctx_blog,
+    ctx_docstrings,
+    ctx_draft,
+    ctx_paths,
+)
 
 
 def blog_callback(ctx: click.Context, param: click.Parameter, value: bool) -> bool:
@@ -21,13 +26,22 @@ def draft_callback(ctx: click.Context, param: click.Parameter, value: bool) -> b
     return value
 
 
+def find_paths_callback(
+    ctx: click.Context, param: click.Parameter, value: bool
+) -> bool:
+    result = [item.strip() for item in value.split(";") if item.strip()]
+    ctx_paths.set(result)
+    return result
+
+
 blog_option = click.option(
     "--blog/--no-blog",
     default=True,
     expose_value=False,
     callback=blog_callback,
     help="Build blog.",
 )
+
 docstrings_option = click.option(
     "--docstrings/--no-docstrings",
     default=True,
@@ -43,13 +57,24 @@ def draft_callback(ctx: click.Context, param: click.Parameter, value: bool) -> b
     help="Don't fail if repositories are missing.",
 )
 
+paths_option = click.option(
+    "--paths",
+    envvar="PULPDOCS_PATHS",
+    expose_value=False,
+    default="",
+    callback=find_paths_callback,
+    help="A semicolon separated list of repository paths. Accept glob patterns.",
+)
+
+
 main = mkdocs_cli
 
 for command_name in ["build", "serve"]:
     sub_command = main.commands.get(command_name)
     draft_option(sub_command)
     blog_option(sub_command)
     docstrings_option(sub_command)
+    paths_option(sub_command)
     serve_options = sub_command.params
     config_file_opt = next(filter(lambda opt: opt.name == "config_file", serve_options))
     config_file_opt.envvar = "PULPDOCS_DIR"

src/pulp_docs/context.py

@@ -4,3 +4,4 @@
 ctx_blog = ContextVar("ctx_blog", default=True)
 ctx_docstrings = ContextVar("ctx_docstrings", default=True)
 ctx_draft = ContextVar("ctx_draft", default=False)
+ctx_paths = ContextVar("ctx_paths", default=None)

src/pulp_docs/plugin.py

@@ -3,19 +3,20 @@
 import json
 import tomllib
 import yaml
+import glob
 
 import httpx
 from git import Repo, GitCommandError
 from mkdocs.config import Config, config_options
 from mkdocs.config.defaults import MkDocsConfig
 from mkdocs.exceptions import PluginError
-from mkdocs.plugins import event_priority, get_plugin_logger, BasePlugin
+from mkdocs.plugins import get_plugin_logger, BasePlugin
 from mkdocs.structure.files import File, Files
 from mkdocs.structure.nav import Navigation, Section, Link
 from mkdocs.structure.pages import Page
 from mkdocs.utils.templates import TemplateContext
 
-from pulp_docs.context import ctx_blog, ctx_docstrings, ctx_draft
+from pulp_docs.context import ctx_blog, ctx_docstrings, ctx_draft, ctx_paths
 
 log = get_plugin_logger(__name__)
 
@@ -34,6 +35,33 @@ class ComponentOption(Config):
     git_url = config_options.Type(str, default="")
     rest_api = config_options.Type(str, default="")
 
+    _repository_dir = None
+
+    @property
+    def repository_dir(self):
+        if not self._repository_dir:
+            raise RuntimeError(
+                "Can't get repository/component path before resolving the dir in the filesystem."
+            )
+        return self._repository_dir
+
+    @property
+    def component_dir(self):
+        return self.repository_dir.parent / self.path
+
+    def resolve_location(self, find_paths: list[str]):
+        repository_name = self.path.split("/")[0]
+        expanded_paths = []
+        for dir in find_paths:
+            expanded_paths.extend(glob.glob(dir))
+        for dir in expanded_paths:
+            dir = Path(dir)
+            component_dir = dir.parent / self.path
+            if repository_name == dir.name and component_dir.exists():
+                self._repository_dir = dir
+                return self._repository_dir
+        return None
+
 
 class PulpDocsPluginConfig(Config):
     components = config_options.ListOfItems(ComponentOption, default=[])
@@ -234,13 +262,15 @@ def on_config(self, config: MkDocsConfig) -> MkDocsConfig | None:
 
         self.pulp_docs_dir = Path(config.docs_dir).parent
         self.repositories_dir = self.pulp_docs_dir.parent
+        self.find_paths = ctx_paths.get() or [f"{self.repositories_dir}/*"]
 
         mkdocstrings_config = config.plugins["mkdocstrings"].config
         components_var = []
         new_components = []
         for component in self.config.components:
-            component_dir = self.repositories_dir / component.path
-            if component_dir.exists():
+            found_location = component.resolve_location(self.find_paths)
+            if found_location:
+                component_dir = component.component_dir
                 components_var.append(component_data(component, component_dir))
                 config.watch.append(str(component_dir / "docs"))
                 mkdocstrings_config.handlers["python"]["paths"].append(
@@ -253,6 +283,7 @@ def on_config(self, config: MkDocsConfig) -> MkDocsConfig | None:
                 else:
                     raise PluginError(f"Component '{component.title}' missing.")
         self.config.components = new_components
+        log.info(f"Using components={[str(c.component_dir) for c in new_components]}")
 
         macros_plugin = config.plugins["macros"]
         macros_plugin.register_macros({"rss_items": rss_items})
@@ -273,10 +304,10 @@ def on_files(self, files: Files, /, *, config: MkDocsConfig) -> Files | None:
         user_nav: dict[str, t.Any] = {}
         dev_nav: dict[str, t.Any] = {}
         for component in self.config.components:
-            component_dir = self.repositories_dir / component.path
+            component_dir = component.component_dir
 
             log.info(f"Fetching docs from '{component.title}'.")
-            git_repository_dir = self.repositories_dir / Path(component.path).parts[0]
+            git_repository_dir = component.repository_dir
             try:
                 git_branch = Repo(git_repository_dir).active_branch.name
             except TypeError:
@@ -290,7 +321,7 @@ def on_files(self, files: Files, /, *, config: MkDocsConfig) -> Files | None:
             else:
                 component_docs_dir = component_dir / "docs"
             component_slug = Path(component_dir.name)
-            assert component_docs_dir.exists()
+            assert component_docs_dir.exists(), component_docs_dir
 
             component_nav = ComponentNav(config, component_slug)