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

{bst_docs-0.0.2 → bst_docs-0.0.3}/LICENSE

@@ -5,4 +5,3 @@ Permission is hereby granted, free of charge, to any person obtaining a copy of
 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.2 → bst_docs-0.0.3}/PKG-INFO

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

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

@@ -8,6 +8,7 @@ import click
 import tqdm
 
 from bst_docs.load_contents import load_project
+from bst_docs.render import RenderConfig
 
 
 @click.command()
@@ -38,6 +39,24 @@ from bst_docs.load_contents import load_project
         " otherwise pure Commonmark markdown will be used"
     ),
 )
+@click.option(
+    "--html-links",
+    default=False,
+    required=False,
+    help=(
+        "If true, markdown link extensions will be converted to .html"
+        " and html elements will be enabled"
+    ),
+)
+@click.option(
+    "--all-html-fixes",
+    default=False,
+    required=False,
+    help=(
+        "If true, all html level fixes will be applied"
+        " This is designed for when html rendering will be done after the fact"
+    ),
+)
 @click.argument("path", default=".")
 def build(
     path: str,
@@ -45,7 +64,9 @@ def build(
     **kwargs: str,
 ) -> None:
     """Generate documentation for a BuildStream project."""
-    html_elements: bool = bool(kwargs.get("html_elements"))
+    config = RenderConfig(
+        **kwargs,
+    )
 
     if kwargs.get("clean"):
         shutil.rmtree(".cache")
@@ -70,7 +91,7 @@ def build(
                 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)
+        f.write_file(dst, config=config)
 
 
 if __name__ == "__main__":

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

@@ -8,7 +8,12 @@ from pathlib import Path
 
 import mdformat
 
-from bst_docs.render import add_summary_block, render_code_section, render_value
+from bst_docs.render import (
+    RenderConfig,
+    add_summary_block,
+    render_code_section,
+    render_value,
+)
 
 
 # TODO: replace this with builstream element
@@ -71,7 +76,7 @@ class Element:
     def _format_link_list(
         self,
         depend_kind: str,
-        use_html: bool,
+        config: RenderConfig,
         depends_dict: dict,
     ) -> str:
         """Format a dependency list as HTML or Markdown links."""
@@ -79,6 +84,8 @@ class Element:
         if not depend_items:
             return ""
 
+        link_ext = ".html" if config.use_html_exts else ".md"
+
         link_list = []
         for item in depend_items:
             rendered = ""
@@ -88,25 +95,27 @@ class Element:
                     rel_path = os.path.relpath(
                         (self.element_base / item),
                         self.absolute_path.parent,
-                    ).replace(".bst", ".md")
+                    ).replace(".bst", link_ext)
                     rendered = (
                         (
                             f'<a href="{rel_path}">{item}</a>'
-                            if use_html
+                            if config.use_html
                             else f"[{item}]({rel_path})"
                         )
                         if ":" not in item
-                        else render_value(item)
+                        else render_value(item, config)
                     )
                 case _others:
-                    rendered = render_value(item)
-            link_list.append(f"<li>{rendered}</li>" if use_html else f"- {rendered}")
+                    rendered = render_value(item, config)
+            link_list.append(
+                f"<li>{rendered}</li>" if config.use_html else f"- {rendered}",
+            )
         content = (
             f"<ul>\n{'\n'.join(link_list)}\n<ul>"  # no hard tabs
-            if use_html
+            if config.use_html
             else "\n".join(link_list)
         )
-        return add_summary_block(depend_kind.title(), content, use_html)
+        return add_summary_block(depend_kind.title(), content, config)
 
     def all_dependencies(self) -> dict[str, list]:
         """All dependencies of this element."""
@@ -115,16 +124,16 @@ class Element:
             output[depend_kind] = self._conf.get(depend_kind, [])
         return output
 
-    def _render_field(self, element: str, use_html: bool) -> str:
+    def _render_field(self, element: str, config: RenderConfig) -> str:
         """Render a named configuration field as a section."""
         return (
             f"## {element.title()}\n\n"
-            + render_value(self._conf.get(element, {}), use_html)
+            + render_value(self._conf.get(element, {}), config)
             if self._conf.get(element, {})
             else ""
         )
 
-    def summary_page(self, use_html: bool) -> str:
+    def summary_page(self, config: RenderConfig) -> str:
         """Generate the full summary page content for this element."""
         return f"""
 # {Path(self.name).name}
@@ -134,33 +143,33 @@ class Element:
 
 ## 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)}
+{self._format_link_list("depends", config, self._conf)}
+{self._format_link_list("build-depends", config, self._conf)}
+{self._format_link_list("runtime-depends", config, 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._format_link_list("depends", config, self.dependants)}
+{self._format_link_list("build-depends", config, self.dependants)}
+{self._format_link_list("runtime-depends", config, 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)}
+{self._render_field("variables", config)}
+{self._render_field("environment", config)}
+{self._render_field("environment-nocache", config)}
+{self._render_field("config", config)}
+{self._render_field("public", config)}
+{self._render_field("sources", config)}
 
 ## Raw Content
 
-{add_summary_block("Raw Text", render_code_section(self.raw, use_html), use_html)}
+{add_summary_block("Raw Text", render_code_section(self.raw, config), config)}
 
 """
 
-    def write_file(self, parent: Path, use_html: bool) -> None:
+    def write_file(self, parent: Path, config: RenderConfig) -> 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 = self.summary_page(config)
         text = mdformat.text(text).replace("\t", "    ")
         dst.write_text(text)
         logging.debug("Logged element % to %", self.name, dst)

bst_docs-0.0.3/bst_docs/render.py

@@ -0,0 +1,115 @@
+"""Rendering utilities for HTML and Markdown output."""
+
+import dataclasses
+from typing import Any
+
+
+@dataclasses.dataclass
+class RenderConfig:
+    """Configuration for rendering output."""
+
+    all_html_fixes: bool
+    use_html: bool
+    use_html_exts: bool
+
+    def __init__(self, **kwargs: str) -> None:
+        """Initialize RenderConfig."""
+        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),
+        )
+        self.use_html = self.all_html_fixes or bool(
+            kwargs.get("html-elements", False),
+        )
+
+
+def html_ul_from_list(list_obj: list, config: RenderConfig) -> str:
+    """Render a list as an HTML unordered list."""
+    return f"""
+<ul>
+{"\n".join(f"<li>{render_value(x, config)}</li>" for x in list_obj)}
+</ul>
+"""
+
+
+def html_br_from_list(list_obj: list, config: RenderConfig) -> str:
+    """Render a list with HTML line breaks."""
+    return f"""
+{"\n<br />".join(render_value(x, config) for x in list_obj)}
+"""
+
+
+def html_table_from_dict(d: dict, config: RenderConfig) -> str:
+    """Render a dictionary as an HTML table."""
+    table_elements: str = "\n".join(
+        f"<tr><td>{key}</td><td>{render_value(val, config)}</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,  # noqa: ANN401
+    config: RenderConfig,
+) -> str:
+    """Render a value (dict, list, or scalar) as HTML or Markdown."""
+    out = ""
+    match v:
+        case dict():
+            out = (
+                html_table_from_dict(v, config)
+                if config.use_html
+                else md_table_from_dict(v)
+            )
+        case list() | set():
+            out = (
+                (
+                    html_ul_from_list(v, config)
+                    if v and not isinstance(v[0], dict)
+                    else html_br_from_list(v, config)
+                )
+                if config.use_html
+                else "\n- ".join(render_value(x, config) for x in v)
+            )
+        case _others:
+            out = (
+                f"<code>{str(v).strip().replace('\n', '</br>')}</code>"
+                if config.use_html
+                else f"`{str(v).strip()}`"
+            )
+    return out
+
+
+def add_summary_block(summary: str, content: str, config: RenderConfig) -> str:
+    """Wrap content in an HTML details/summary block or plain text."""
+    if not config.use_html:
+        return summary + "\n" + content
+    return f"""
+<details open>
+    <summary>{summary}</summary>
+    {content}
+</details>
+"""
+
+
+def render_code_section(content: str, config: RenderConfig) -> str:
+    """Render a multiline code block."""
+    output = content
+    if config.use_html:
+        output = f"<pre><code>{content}</code></pre>"
+    else:
+        output = f"```\n{content.replace('```', r'\`\`\`')}\n```"
+    return output

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

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

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

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

bst_docs-0.0.2/bst_docs/render.py

@@ -1,87 +0,0 @@
-"""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