bst-docs 0.0.3__tar.gz → 0.0.4__tar.gz

{bst_docs-0.0.3 → bst_docs-0.0.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: bst-docs
-Version: 0.0.3
+Version: 0.0.4
 Summary: API Reference Generator for Buildstream Projects
 Author-email: Aedan McHale <aedan.mchale@gmail.com>
 License-Expression: MIT

{bst_docs-0.0.3 → bst_docs-0.0.4}/bst_docs/build.py

@@ -30,6 +30,12 @@ from bst_docs.render import RenderConfig
     required=False,
     help="Remove all files from cache & output directories",
 )
+@click.option(
+    "--load-includes",
+    default=True,
+    required=False,
+    help="Load content from file includes",
+)
 @click.option(
     "--html-elements",
     default=True,
@@ -64,10 +70,7 @@ def build(
     **kwargs: str,
 ) -> None:
     """Generate documentation for a BuildStream project."""
-    config = RenderConfig(
-        **kwargs,
-    )
-
+    config = RenderConfig(**kwargs)
     if kwargs.get("clean"):
         shutil.rmtree(".cache")
         logging.warning("Nuking cache: %s", ".cache")
@@ -79,12 +82,12 @@ def build(
         logging.warning("Overwriting %s", dst)
         shutil.rmtree(dst)
         dst.mkdir()
-    files, _config = load_project(path)
+    files, _config = load_project(path, bool(kwargs.get("load_includes")))
 
     for f in tqdm.tqdm(files, "Finding dependants"):
         for kind, dependencies in f.all_dependencies().items():
             for dep in dependencies:
-                dep = dep if isinstance(dep, str) else dep["filename"]
+                dep = dep if isinstance(dep, str) else dep.get("filename", "")
                 try:
                     element_dep = next(x for x in files if x.bst_name == dep)
                     element_dep.dependants[kind].append(f.bst_name)

{bst_docs-0.0.3 → bst_docs-0.0.4}/bst_docs/element.py

@@ -8,6 +8,7 @@ from pathlib import Path
 
 import mdformat
 
+from bst_docs.includes import INCLUDE_KEY, load_include, meld_confs
 from bst_docs.render import (
     RenderConfig,
     add_summary_block,
@@ -24,7 +25,7 @@ class Element:
     _conf: dict
     raw: str
 
-    def __init__(self, _conf: dict, raw: str) -> None:
+    def __init__(self, _conf: dict, raw: str, load_includes: bool) -> None:
         """Initialize Element."""
         self._conf = _conf
         self.raw = raw
@@ -33,6 +34,17 @@ class Element:
             "build-depends": [],
             "runtime-depends": [],
         }
+        if load_includes:
+            self.load_includes()
+
+    def load_includes(self) -> None:
+        """Import all includes into element conf."""
+        if includes := self._conf.get(INCLUDE_KEY):
+            includes = [includes] if not isinstance(includes, list) else includes
+            self._conf.pop(INCLUDE_KEY)
+            for file in includes:
+                include_conf = load_include(self.project_base, file)
+                self._conf = meld_confs(self._conf, include_conf)
 
     @property
     def name(self) -> str:
@@ -124,10 +136,15 @@ class Element:
             output[depend_kind] = self._conf.get(depend_kind, [])
         return output
 
-    def _render_field(self, element: str, config: RenderConfig) -> str:
+    def _render_field(
+        self,
+        element: str,
+        config: RenderConfig,
+        title: str | None = None,
+    ) -> str:
         """Render a named configuration field as a section."""
         return (
-            f"## {element.title()}\n\n"
+            f"## {title.title() if title else element.title()}\n\n"
             + render_value(self._conf.get(element, {}), config)
             if self._conf.get(element, {})
             else ""
@@ -141,6 +158,7 @@ class Element:
 `{self._conf.get("kind", "Unknown")}`
 {self.description or "--"}
 
+
 ## Dependencies
 
 {self._format_link_list("depends", config, self._conf)}

bst_docs-0.0.4/bst_docs/includes.py

@@ -0,0 +1,47 @@
+"""Handle loading configurations from includes."""
+
+from pathlib import Path
+
+from yaml import safe_load
+
+INCLUDE_KEY = "(@)"
+
+
+def meld_confs(conf1: dict, conf2: dict) -> dict:
+    """Merge two configuration dictionaries together."""
+    output = {}
+    for key in list(conf1.keys()) + list(conf2.keys()):
+        v1 = conf1.get(key)
+        v2 = conf2.get(key)
+        if v1 is None or v2 is None:
+            output[key] = v1 or v2
+            continue
+        if v1 == v2:
+            output[key] = v1
+            continue
+        match (v1, v2):
+            case (dict(), dict()):
+                output[key] = v1 | v2
+            case (list(), list()):
+                output[key] = v1 + v2
+            case (dict(), list()) | (list(), dict()):
+                list_el = v1 if isinstance(v1, list) else v2
+                dict_el = v1 if isinstance(v1, dict) else v2
+                output[key] = [*list_el, dict_el]
+
+            case _others:
+                raise TypeError(f"{type(v1), type(v2)}")
+    return output
+
+
+def load_include(project_base: Path, include_name: str) -> dict:
+    """Load an include and all of it's includes."""
+    real_path = project_base / include_name
+    output = safe_load((real_path).read_text())
+    if includes := output.get(INCLUDE_KEY):
+        output.pop(INCLUDE_KEY)
+        includes = [includes] if not isinstance(includes, list) else includes
+        for i in includes:
+            conf = load_include(project_base, i)
+            output = meld_confs(output, conf)
+    return output

{bst_docs-0.0.3 → bst_docs-0.0.4}/bst_docs/load_contents.py

@@ -3,6 +3,7 @@
 import logging
 from pathlib import Path
 
+import tqdm
 import validators
 from git import Repo
 from yaml import safe_load
@@ -13,7 +14,7 @@ DEFAULT_PROJECT_CONF = "project.conf"
 CACHE_DIR = Path("./.cache")
 
 
-def load_project(path: str | Path) -> tuple[list[Element], dict]:
+def load_project(path: str | Path, load_includes: bool) -> tuple[list[Element], dict]:
     """Load a BuildStream project from a URL or local path."""
     output = ([], {})
     if validators.url(path):
@@ -25,11 +26,11 @@ def load_project(path: str | Path) -> tuple[list[Element], dict]:
             logging.info("Using cached %s", git_repo_name)
         path = CACHE_DIR / git_repo_name
     if Path(path).resolve().exists():
-        output = load_local_project(Path(path).resolve())
+        output = load_local_project(Path(path).resolve(), load_includes)
     return output
 
 
-def load_local_project(path: Path) -> tuple[list[Element], dict]:
+def load_local_project(path: Path, load_includes: bool) -> tuple[list[Element], dict]:
     """Load a BuildStream project from a local filesystem path."""
     conf_path: Path = path / DEFAULT_PROJECT_CONF
     assert (conf_path).exists(), "Project could not be loaded (no configuration file)"
@@ -37,7 +38,7 @@ def load_local_project(path: Path) -> tuple[list[Element], dict]:
     element_path: Path = path / conf.get("element-path", "elements")
     assert (conf_path).exists(), "Project could not be loaded (no element path)"
     elements: list[Element] = []
-    for f in element_path.glob("**/*.bst"):
+    for f in tqdm.tqdm(list(element_path.glob("**/*.bst")), "Loading Elements"):
         raw = f.read_text("utf-8")
         yml = safe_load(raw)
         elements.append(
@@ -49,6 +50,7 @@ def load_local_project(path: Path) -> tuple[list[Element], dict]:
                     "element_path": element_path.relative_to(path),
                 },
                 raw,
+                load_includes=load_includes,
             ),
         )
     return elements, conf

{bst_docs-0.0.3 → bst_docs-0.0.4}/bst_docs/render.py

@@ -14,12 +14,12 @@ class RenderConfig:
 
     def __init__(self, **kwargs: str) -> None:
         """Initialize RenderConfig."""
-        self.all_html_fixes = bool(kwargs.get("all-html-fixes", False))
+        self.all_html_fixes = bool(kwargs.get("all_html_fixes", False))
         self.use_html_exts = self.all_html_fixes or bool(
-            kwargs.get("use-html-exts", False),
+            kwargs.get("use_html_exts", False),
         )
         self.use_html = self.all_html_fixes or bool(
-            kwargs.get("html-elements", False),
+            kwargs.get("html_elements", False),
         )
 
 

{bst_docs-0.0.3 → bst_docs-0.0.4}/bst_docs.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: bst-docs
-Version: 0.0.3
+Version: 0.0.4
 Summary: API Reference Generator for Buildstream Projects
 Author-email: Aedan McHale <aedan.mchale@gmail.com>
 License-Expression: MIT

{bst_docs-0.0.3 → bst_docs-0.0.4}/bst_docs.egg-info/SOURCES.txt

@@ -5,6 +5,7 @@ bst_docs/__init__.py
 bst_docs/__main__.py
 bst_docs/build.py
 bst_docs/element.py
+bst_docs/includes.py
 bst_docs/load_contents.py
 bst_docs/render.py
 bst_docs.egg-info/PKG-INFO

{bst_docs-0.0.3 → bst_docs-0.0.4}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "bst-docs"
-version = "0.0.3"
+version = "0.0.4"
 readme = "README.md"
 authors = [{ name = "Aedan McHale", email = "aedan.mchale@gmail.com" }]
 license = "MIT"