bst-docs 0.0.1__py3-none-any.whl

bst_docs/__init__.py

@@ -0,0 +1 @@
+"""API reference generator for buildstream projects."""

bst_docs/__main__.py

@@ -0,0 +1,16 @@
+"""CLI entry point for bst_docs."""
+
+import click
+
+from bst_docs.build import build
+
+
+@click.group()
+def cli() -> None:
+    """CLI group for bst_docs commands."""
+
+
+cli.add_command(build)
+
+if __name__ == "__main__":
+    cli()

bst_docs/build.py

@@ -0,0 +1,77 @@
+"""Build command for generating documentation."""
+
+import logging
+import shutil
+from pathlib import Path
+
+import click
+import tqdm
+
+from bst_docs.load_contents import load_project
+
+
+@click.command()
+@click.option(
+    "--depth",
+    default=3,
+    required=False,
+    help="Depth of network crawling to perform",
+)
+@click.option(
+    "--output",
+    default="./output",
+    required=False,
+    help="Destination folder for markdown files",
+)
+@click.option(
+    "--clean",
+    default=False,
+    required=False,
+    help="Remove all files from cache & output directories",
+)
+@click.option(
+    "--html-elements",
+    default=True,
+    required=False,
+    help=(
+        "If true, html elements will be embedded in markdown files"
+        "otherwise pure Commonmark markdown will be used"
+    ),
+)
+@click.argument("path", default=".")
+def build(
+    path: str,
+    output: str,
+    **kwargs: str,
+) -> None:
+    """Generate documentation for a BuildStream project."""
+    html_elements: bool = bool(kwargs.get("html_elements"))
+
+    if kwargs.get("clean"):
+        shutil.rmtree(".cache")
+        logging.warning("Nuking cache: %s", ".cache")
+
+    dst = Path(output)
+    try:
+        dst.mkdir()
+    except Exception:
+        logging.warning("Overwriting %s", dst)
+        shutil.rmtree(dst)
+        dst.mkdir()
+    files, _config = load_project(path)
+
+    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"]
+                try:
+                    element_dep = next(x for x in files if x.bst_name == dep)
+                    element_dep.dependants[kind].append(f.bst_name)
+                except StopIteration:
+                    logging.warning(str(f"Unfound dependency {dep} for {f.name}"))
+    for f in tqdm.tqdm(files, "Writing Output"):
+        f.write_file(dst, use_html=html_elements)
+
+
+if __name__ == "__main__":
+    build.main()

bst_docs/element.py

@@ -0,0 +1,166 @@
+"""Element data model for BuildStream project elements."""
+
+import dataclasses
+import logging
+import os
+import re
+from pathlib import Path
+
+import mdformat
+
+from bst_docs.render import add_summary_block, render_code_section, render_value
+
+
+# TODO: replace this with builstream element
+@dataclasses.dataclass
+class Element:
+    """BST Element representation."""
+
+    _conf: dict
+    raw: str
+
+    def __init__(self, _conf: dict, raw: str) -> None:
+        """Initialize Element."""
+        self._conf = _conf
+        self.raw = raw
+        self.dependants: dict[str, list] = {
+            "depends": [],
+            "build-depends": [],
+            "runtime-depends": [],
+        }
+
+    @property
+    def name(self) -> str:
+        """Return the element path."""
+        return str(self._conf.get("path", ""))
+
+    @property
+    def bst_name(self) -> str:
+        """Return the element path."""
+        return re.sub(f"^{self._conf.get('element_path', '')}/", "", self.name)
+
+    @property
+    def doc_path(self) -> str:
+        """Return the markdown file path for this element."""
+        return self.name.replace(".bst", ".md")
+
+    @property
+    def project_base(self) -> Path:
+        """Return the project base path."""
+        return Path(self._conf.get("project_base", ""))
+
+    @property
+    def element_base(self) -> Path:
+        """Return the element subdirectory path."""
+        return self.project_base / self._conf.get("element_path", "")
+
+    @property
+    def absolute_path(self) -> Path:
+        """Return the absolute filesystem path to this element."""
+        return self.project_base / self._conf.get("path", "")
+
+    @property
+    def description(self) -> str:
+        """Return the element description with a summary header."""
+        return (
+            ("## Summary\n\n" + self._conf.get("description", "") + "\n")
+            if self._conf.get("description")
+            else ""
+        )
+
+    def _format_link_list(
+        self,
+        depend_kind: str,
+        use_html: bool,
+        depends_dict: dict,
+    ) -> str:
+        """Format a dependency list as HTML or Markdown links."""
+        depend_items = depends_dict.get(depend_kind, [])
+        if not depend_items:
+            return ""
+
+        link_list = []
+        for item in depend_items:
+            rendered = ""
+
+            match item:
+                case str():
+                    rel_path = os.path.relpath(
+                        (self.element_base / item),
+                        self.absolute_path.parent,
+                    ).replace(".bst", ".md")
+                    rendered = (
+                        (
+                            f'<a href="{rel_path}">{item}</a>'
+                            if use_html
+                            else f"[{item}]({rel_path})"
+                        )
+                        if ":" not in item
+                        else render_value(item)
+                    )
+                case _others:
+                    rendered = render_value(item)
+            link_list.append(f"<li>{rendered}</li>" if use_html else f"- {rendered}")
+        content = (
+            f"<ul>\n{'\n'.join(link_list)}\n<ul>"  # no hard tabs
+            if use_html
+            else "\n".join(link_list)
+        )
+        return add_summary_block(depend_kind.title(), content, use_html)
+
+    def all_dependencies(self) -> dict[str, list]:
+        """All dependencies of this element."""
+        output = {}
+        for depend_kind in ["depends", "runtime-depends", "build-depends"]:
+            output[depend_kind] = self._conf.get(depend_kind, [])
+        return output
+
+    def _render_field(self, element: str, use_html: bool) -> str:
+        """Render a named configuration field as a section."""
+        return (
+            f"## {element.title()}\n\n"
+            + render_value(self._conf.get(element, {}), use_html)
+            if self._conf.get(element, {})
+            else ""
+        )
+
+    def summary_page(self, use_html: bool) -> str:
+        """Generate the full summary page content for this element."""
+        return f"""
+# {Path(self.name).name}
+
+`{self._conf.get("kind", "Unknown")}`
+{self.description or "--"}
+
+## Dependencies
+
+{self._format_link_list("depends", use_html, self._conf)}
+{self._format_link_list("build-depends", use_html, self._conf)}
+{self._format_link_list("runtime-depends", use_html, self._conf)}
+
+## Dependants
+{self._format_link_list("depends", use_html, self.dependants)}
+{self._format_link_list("build-depends", use_html, self.dependants)}
+{self._format_link_list("runtime-depends", use_html, self.dependants)}
+
+{self._render_field("variables", use_html)}
+{self._render_field("environment", use_html)}
+{self._render_field("environment-nocache", use_html)}
+{self._render_field("config", use_html)}
+{self._render_field("public", use_html)}
+{self._render_field("sources", use_html)}
+
+## Raw Content
+
+{add_summary_block("Raw Text", render_code_section(self.raw, use_html), use_html)}
+
+"""
+
+    def write_file(self, parent: Path, use_html: bool) -> None:
+        """Write the rendered summary page to disk."""
+        dst = parent / self.doc_path
+        dst.parent.mkdir(parents=True, exist_ok=True)
+        text = self.summary_page(use_html)
+        text = mdformat.text(text).replace("\t", "    ")
+        dst.write_text(text)
+        logging.debug("Logged element % to %", self.name, dst)

bst_docs/load_contents.py

@@ -0,0 +1,54 @@
+"""Load and parse BuildStream project configuration."""
+
+import logging
+from pathlib import Path
+
+import validators
+from git import Repo
+from yaml import safe_load
+
+from bst_docs.element import Element
+
+DEFAULT_PROJECT_CONF = "project.conf"
+CACHE_DIR = Path("./.cache")
+
+
+def load_project(path: str | Path) -> tuple[list[Element], dict]:
+    """Load a BuildStream project from a URL or local path."""
+    output = ([], {})
+    if validators.url(path):
+        git_repo_name = str(path).split("/")[-1].replace(".git", "")
+        dst_repo = CACHE_DIR / git_repo_name
+        if not dst_repo.exists():
+            Repo.clone_from(path, dst_repo)
+        else:
+            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())
+    return output
+
+
+def load_local_project(path: Path) -> 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)"
+    conf = safe_load(conf_path.read_text())
+    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"):
+        raw = f.read_text("utf-8")
+        yml = safe_load(raw)
+        elements.append(
+            Element(
+                yml
+                | {
+                    "path": f.relative_to(path),
+                    "project_base": path,
+                    "element_path": element_path.relative_to(path),
+                },
+                raw,
+            ),
+        )
+    return elements, conf

bst_docs/render.py

@@ -0,0 +1,87 @@
+"""Rendering utilities for HTML and Markdown output."""
+
+from typing import Any
+
+
+def html_ul_from_list(list_obj: list) -> str:
+    """Render a list as an HTML unordered list."""
+    return f"""
+<ul>
+{"\n".join(f"<li>{render_value(x)}</li>" for x in list_obj)}
+</ul>
+"""
+
+
+def html_br_from_list(list_obj: list) -> str:
+    """Render a list with HTML line breaks."""
+    return f"""
+{"\n<br />".join(render_value(x, True) for x in list_obj)}
+"""
+
+
+def html_table_from_dict(d: dict) -> str:
+    """Render a dictionary as an HTML table."""
+    table_elements: str = "\n".join(
+        f"<tr><td>{key}</td><td>{render_value(val)}</td></tr>" for key, val in d.items()
+    )
+    return f"""
+<table>
+    {table_elements}
+</table>
+"""
+
+
+def md_table_from_dict(d: dict) -> str:
+    """Render a dictionary as a Markdown table."""
+    return f"""
+|  |  |
+|--|--|
+{"\n".join(f"|{key}|{val!s}|" for key, val in d.items())}
+"""
+
+
+def render_value(v: Any, use_html: bool = True) -> str:  # noqa: ANN401
+    """Render a value (dict, list, or scalar) as HTML or Markdown."""
+    out = ""
+    match v:
+        case dict():
+            out = html_table_from_dict(v) if use_html else md_table_from_dict(v)
+        case list() | set():
+            out = (
+                (
+                    html_ul_from_list(v)
+                    if v and not isinstance(v[0], dict)
+                    else html_br_from_list(v)
+                )
+                if use_html
+                else "\n- ".join(render_value(x, use_html) for x in v)
+            )
+        case _others:
+            out = (
+                f"<code>{str(v).strip().replace('\n', '</br>')}</code>"
+                if use_html
+                else f"`{str(v).strip()}`"
+            )
+    return out
+
+
+def add_summary_block(summary: str, content: str, use_html: bool) -> str:
+    """Wrap content in an HTML details/summary block or plain text."""
+    if not use_html:
+        return summary + "\n" + content
+    return f"""
+<details>
+    <summary>{summary}</summary>
+    {content}
+</details>
+"""
+
+
+def render_code_section(content: str, use_html: bool) -> str:
+    """Render a multiline code block."""
+    output = content
+    if use_html:
+        output = f"<pre><code>{content}</code></pre>"
+    else:
+        output = f"```\n{content.replace('```', r'\`\`\`')}\n```"
+    return output

bst_docs-0.0.1.dist-info/METADATA

@@ -0,0 +1,71 @@
+Metadata-Version: 2.4
+Name: bst-docs
+Version: 0.0.1
+Summary: API Reference Generator for Buildstream Projects
+Author-email: Aedan McHale <aedan.mchale@gmail.com>
+License-Expression: MIT
+Project-URL: Homepage, https://gitlab.com/Aedan.mchale/bst-docs
+Classifier: Programming Language :: Python
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Software Development :: Build Tools
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: buildstream>=2.7.0
+Requires-Dist: click>=8.4.1
+Requires-Dist: gitpython>=3.1.50
+Requires-Dist: mdformat>=1.0.0
+Requires-Dist: pyyaml>=6.0.3
+Requires-Dist: tqdm>=4.68.2
+Requires-Dist: ty>=0.0.43
+Requires-Dist: validators>=0.35.0
+Provides-Extra: dev
+Requires-Dist: build>=1.5.0; extra == "dev"
+Requires-Dist: prek>=0.4.4; extra == "dev"
+Requires-Dist: ruff>=0.15.15; extra == "dev"
+Requires-Dist: twine>=6.2.0; extra == "dev"
+Requires-Dist: zensical>=0.0.44; extra == "dev"
+Dynamic: license-file
+
+# bst-docs
+
+This is a 
+
+## Usage
+
+To build a documentation folder for a given repo:
+`uv run bst-docs build $REPO_PATH`
+
+Or to build a documentation folder for a network repo (clones using your `.netrc`):
+`uv run bst-docs build $REPO_URL`
+
+These commands will produce a folder full of markdown files which can then be imported into the documentation portal of your choosing.
+
+An example zensical.toml has been provided to view the results in `./output`, to use:
+`uv run zensical serve`
+
+### Configuration Options
+
+```shell
+Usage: bst-docs build [OPTIONS] [PATH]
+
+Options:
+  --depth INTEGER          Depth of network crawling to perform
+  --output TEXT            Destination folder for markdown files
+  --clean BOOLEAN          Remove all files from cache & output directories
+  --html-elements BOOLEAN  If true, html elements will be embedded in markdown
+                           files otherwise pure Commonmark markdown will be
+                           used
+  --overwrite BOOLEAN      Overwrite output directory if true, otherwise
+                           errors if output files exist
+  --help                   Show this message and exit.
+```
+
+## Design Choices
+
+- Should be possible to render everything as MD, html is for nicenesses

bst_docs-0.0.1.dist-info/RECORD

@@ -0,0 +1,12 @@
+bst_docs/__init__.py,sha256=bVzVAPrxVBdHhgcGaigNV_yoNY_oPxGSXD7uLpDxxDg,56
+bst_docs/__main__.py,sha256=g56B2qPR7PS8zZhbMptnQiIhPs1f-jftnVlb6CVwqbg,226
+bst_docs/build.py,sha256=e2xjP5KGj8_Z-L3DwT5aqihc4j7S16TCsOqe177lcjU,2009
+bst_docs/element.py,sha256=QoM3y85Qgg-HvbBgOAy9iBWlzjp0MG4qjZTVIAFANZk,5359
+bst_docs/load_contents.py,sha256=O3GeeQbD2ny0-KWCpazja0WuNj3fUyy79TqW5WTQULA,1815
+bst_docs/render.py,sha256=Z3Vn5knMo84_vQyja5tfU1Jrjk3jM1Y9MMrieYvz7cw,2328
+bst_docs-0.0.1.dist-info/licenses/LICENSE,sha256=IMK1Cqf2Y26SwoVQqgqEeii3KR-HKi7O3Qf3Jecc5vM,1061
+bst_docs-0.0.1.dist-info/METADATA,sha256=ZzsNrqUil3JiZkZifehQblpANhMlxss4mKIIe9Tm-cw,2469
+bst_docs-0.0.1.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+bst_docs-0.0.1.dist-info/entry_points.txt,sha256=abhS86AQY9SzCI1mTzD8mmPd-6oRbc7xEqUvi3fy8-4,51
+bst_docs-0.0.1.dist-info/top_level.txt,sha256=3fYXMvehhejDN7TTvOT0B_rX8MO3Ob4ZcX7H6iQR_qk,9
+bst_docs-0.0.1.dist-info/RECORD,,

bst_docs-0.0.1.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

bst_docs-0.0.1.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+bst-docs = bst_docs.__main__:cli

bst_docs-0.0.1.dist-info/licenses/LICENSE

@@ -0,0 +1,8 @@
+Copyright 2026 Aedan McHale
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+

bst_docs-0.0.1.dist-info/top_level.txt

@@ -0,0 +1 @@
+bst_docs