sphinx-data2table 0.1.1__tar.gz

sphinx_data2table-0.1.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 jagarikokamukamu
+
+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.

sphinx_data2table-0.1.1/PKG-INFO

@@ -0,0 +1,12 @@
+Metadata-Version: 2.4
+Name: sphinx-data2table
+Version: 0.1.1
+Summary: Sphinx data-table extension for TOML, YAML, and JSON with Markdown cell parsing
+Author: jagarikokamukamu
+License-Expression: MIT
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pyyaml>=6.0.3
+Requires-Dist: sphinx>=8.0
+Dynamic: license-file

sphinx_data2table-0.1.1/pyproject.toml

@@ -0,0 +1,73 @@
+[project]
+name = "sphinx-data2table"
+version = "0.1.1"
+description = "Sphinx data-table extension for TOML, YAML, and JSON with Markdown cell parsing"
+readme = "README.md"
+license = "MIT"
+authors = [{ name = "jagarikokamukamu" }]
+requires-python = ">=3.12"
+dependencies = ["pyyaml>=6.0.3", "sphinx>=8.0"]
+
+[build-system]
+requires = ["setuptools>=61.0"]
+build-backend = "setuptools.build_meta"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[dependency-groups]
+dev = [
+    "bandit>=1.9.4",
+    "myst-parser>=5.1.0",
+    "pip-audit>=2.10.1",
+    "pyright>=1.1.411",
+    "pytest-cov>=7.1.0",
+    "pytest>=9.1.1",
+    "ruff>=0.16.0",
+]
+
+[tool.pytest.ini_options]
+pythonpath = ["src"]
+testpaths = ["tests"]
+
+[tool.bandit]
+exclude_dirs = ["tests", ".venv"]
+skips = ["B110"]
+
+[tool.ruff]
+line-length = 88
+target-version = "py313"
+
+[tool.ruff.lint]
+select = [
+    "E",    # pycodestyle errors
+    "W",    # pycodestyle warnings
+    "F",    # pyflakes
+    "I",    # isort
+    "B",    # flake8-bugbear
+    "C4",   # flake8-comprehensions
+    "UP",   # pyupgrade
+    "D100", # Missing docstring in public module (files)
+    "D101", # Missing docstring in public class
+    "D102", # Missing docstring in public method
+    "D103", # Missing docstring in public function
+    "D201",
+    "D202", # missing-blank-line-before-summary
+    "D205", # missing-blank-line-after-summary
+    "D417", # undocumented-param
+]
+ignore = []
+
+[tool.ruff.lint.per-file-ignores]
+"tests/*" = ["D"]
+
+[tool.ruff.format]
+quote-style = "double"
+indent-style = "space"
+
+[tool.ruff.lint.pydocstyle]
+convention = "google"
+
+[tool.pyright]
+pythonVersion = "3.13"
+typeCheckingMode = "basic"

sphinx_data2table-0.1.1/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

sphinx_data2table-0.1.1/src/sphinx_data2table/__init__.py

@@ -0,0 +1,35 @@
+"""Sphinx Data2Table Extension.
+
+Renders TOML, YAML, or JSON data as HTML/LaTeX tables with Markdown cell parsing.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+from sphinx_data2table.directive import DataTableDirective
+
+if TYPE_CHECKING:
+    from sphinx.application import Sphinx
+
+__version__ = "0.1.0"
+
+
+def setup(app: Sphinx) -> dict[str, Any]:
+    """Registers the data-table and datatable directives with the Sphinx application.
+
+    Args:
+        app: The active Sphinx application instance.
+
+    Returns:
+        A dictionary containing metadata about the extension, including
+        version and parallel read/write safety flags.
+    """
+    app.add_directive("data-table", DataTableDirective)
+    app.add_directive("datatable", DataTableDirective)
+
+    return {
+        "version": __version__,
+        "parallel_read_safe": True,
+        "parallel_write_safe": True,
+    }

sphinx_data2table-0.1.1/src/sphinx_data2table/directive.py

@@ -0,0 +1,333 @@
+"""Directive implementation for rendering TOML, YAML, and JSON tables."""
+
+from __future__ import annotations
+
+import contextlib
+import json
+import os
+import textwrap
+import tomllib
+from typing import Any
+
+import yaml
+from docutils import nodes
+from docutils.parsers.rst import Directive, directives
+from docutils.statemachine import StringList
+
+
+class DataTableDirective(Directive):
+    """Sphinx/Docutils directive to render TOML, YAML, or JSON data as tables.
+
+    This directive parses raw inline TOML/YAML/JSON text or external data files
+    into structured data and constructs docutils table nodes. Each cell's text is
+    parsed via nested_parse to support Markdown inline and block elements.
+    """
+
+    has_content = True
+    required_arguments = 0
+    optional_arguments = 0
+    final_argument_whitespace = False
+    option_spec = {
+        "file": directives.path,
+        "format": directives.unchanged,
+        "headers": directives.unchanged,
+    }
+
+    def run(self) -> list[nodes.Node]:
+        """Main execution method invoked by docutils when parsing directive.
+
+        Returns:
+            A list containing constructed docutils table node or error nodes.
+        """
+        env = (
+            self.state.document.settings.env
+            if hasattr(self.state.document.settings, "env")
+            else None
+        )
+
+        # 1. Obtain raw data content
+        file_path = self.options.get("file")
+        raw_text = ""
+
+        if file_path:
+            if env:
+                # Resolve relative path to sphinx doc source directory
+                rel_path, abs_path = env.relfn2path(file_path)
+                env.note_dependency(rel_path)
+            else:
+                abs_path = os.path.abspath(file_path)
+
+            try:
+                with open(abs_path, encoding="utf-8") as f:
+                    raw_text = f.read()
+            except OSError as err:
+                return [
+                    self.state_machine.reporter.error(
+                        f"data-table: Could not read file '{file_path}': {err}",
+                        line=self.lineno,
+                    )
+                ]
+        elif self.content:
+            raw_text = textwrap.dedent("\n".join(self.content)).strip()
+        else:
+            return [
+                self.state_machine.reporter.error(
+                    "data-table: Neither content nor ':file:' option provided.",
+                    line=self.lineno,
+                )
+            ]
+
+        # 2. Determine format (yaml / toml / json)
+        fmt = self.options.get("format", "auto").lower()
+
+        if fmt == "auto":
+            if file_path:
+                ext = os.path.splitext(file_path)[1].lower()
+                if ext in (".toml",):
+                    fmt = "toml"
+                elif ext in (".yaml", ".yml"):
+                    fmt = "yaml"
+                elif ext in (".json",):
+                    fmt = "json"
+            if fmt == "auto":
+                fmt = self._guess_format(raw_text)
+
+        # 3. Parse data
+        data, parse_err = self._parse_data(raw_text, fmt)
+        if parse_err:
+            return [
+                self.state_machine.reporter.error(
+                    f"data-table: Failed to parse {fmt.upper()} data: {parse_err}",
+                    line=self.lineno,
+                )
+            ]
+
+        rows_data = self._normalize_rows(data)
+        if not rows_data:
+            return [
+                self.state_machine.reporter.warning(
+                    "data-table: Data is empty or invalid format.",
+                    line=self.lineno,
+                )
+            ]
+
+        # 4. Determine Headers
+        headers_opt = self.options.get("headers")
+        if headers_opt:
+            headers = [h.strip() for h in headers_opt.split(",") if h.strip()]
+        else:
+            # Collect all unique keys across rows while preserving order
+            headers = []
+            for row in rows_data:
+                if isinstance(row, dict):
+                    for k in row.keys():
+                        if k not in headers:
+                            headers.append(k)
+
+        if not headers:
+            return [
+                self.state_machine.reporter.error(
+                    "data-table: Could not determine headers from data.",
+                    line=self.lineno,
+                )
+            ]
+
+        # 5. Build Docutils Table Node
+        table_node = self._build_table_node(headers, rows_data)
+        return [table_node]
+
+    def _guess_format(self, text: str) -> str:
+        """Guesses whether raw text content is JSON, TOML, or YAML.
+
+        Args:
+            text: The raw string content of the data.
+
+        Returns:
+            The string 'json', 'toml', or 'yaml'. Defaults to 'yaml' if ambiguous.
+        """
+        # Try JSON first
+        with contextlib.suppress(Exception):
+            parsed_json = json.loads(text)
+            if isinstance(parsed_json, (list, dict)):
+                return "json"
+
+        # Try TOML
+        with contextlib.suppress(Exception):
+            parsed_toml = tomllib.loads(text)
+            if isinstance(parsed_toml, dict) and parsed_toml:
+                return "toml"
+
+        # Try YAML
+        with contextlib.suppress(Exception):
+            parsed_yaml = yaml.safe_load(text)
+            if isinstance(parsed_yaml, (list, dict)):
+                return "yaml"
+
+        return "yaml"
+
+    def _parse_data(self, text: str, fmt: str) -> tuple[Any, str | None]:
+        """Parses raw text data using the specified format parser.
+
+        Args:
+            text: Raw data text string.
+            fmt: Format string ('json', 'toml', or 'yaml').
+
+        Returns:
+            A tuple containing (parsed_object, error_message_or_None).
+        """
+        if fmt == "json":
+            try:
+                return json.loads(text), None
+            except Exception as e:
+                return None, str(e)
+        elif fmt == "toml":
+            try:
+                return tomllib.loads(text), None
+            except Exception as e:
+                return None, str(e)
+        elif fmt == "yaml":
+            try:
+                return yaml.safe_load(text), None
+            except Exception as e:
+                return None, str(e)
+        else:
+            return None, f"Unsupported format '{fmt}'. Use 'json', 'yaml', or 'toml'."
+
+    def _normalize_rows(self, data: Any) -> list[dict[str, Any]]:
+        """Normalizes parsed data into a list of row dictionaries.
+
+        Args:
+            data: Parsed data resulting from JSON, TOML, or YAML parser.
+
+        Returns:
+            A list of dictionary objects representing table rows.
+        """
+        if isinstance(data, list):
+            return [item for item in data if isinstance(item, dict)]
+        elif isinstance(data, dict):
+            # If root is a dict containing a list of dicts (e.g. {"items": [...]})
+            for val in data.values():
+                if isinstance(val, list) and all(isinstance(x, dict) for x in val):
+                    return val
+            # Or a single row dict
+            return [data]
+        return []
+
+    def _build_table_node(
+        self, headers: list[str], rows_data: list[dict[str, Any]]
+    ) -> nodes.table:
+        """Constructs docutils table nodes and parses Markdown for each cell.
+
+        Args:
+            headers: A list of column header names.
+            rows_data: A list of row dictionary objects containing cell contents.
+
+        Returns:
+            A docutils.nodes.table instance containing header and body rows.
+        """
+        table = nodes.table()
+        table["classes"] += ["datatable"]
+        tgroup = nodes.tgroup(cols=len(headers))
+        table += tgroup
+
+        for _ in headers:
+            tgroup += nodes.colspec(colwidth=1)
+
+        # Header Row
+        thead = nodes.thead()
+        tgroup += thead
+        header_row = nodes.row()
+        thead += header_row
+
+        for header_text in headers:
+            entry = nodes.entry()
+            self._parse_cell_markdown(str(header_text), entry)
+            header_row += entry
+
+        # Body Rows
+        tbody = nodes.tbody()
+        tgroup += tbody
+
+        for row_dict in rows_data:
+            row_node = nodes.row()
+            tbody += row_node
+            for h in headers:
+                entry = nodes.entry()
+                cell_value = row_dict.get(h, "")
+                if cell_value is None:
+                    cell_value = ""
+                self._parse_cell_markdown(str(cell_value), entry)
+                row_node += entry
+
+        return table
+
+    def _parse_cell_markdown(self, content_str: str, entry_node: nodes.entry) -> None:
+        """Parses cell string as Markdown/reST AST into docutils nodes in entry_node.
+
+        Args:
+            content_str: The raw text content of the table cell.
+            entry_node: Target docutils.nodes.entry node to append child nodes into.
+        """
+        dedented_str = textwrap.dedent(content_str).strip()
+        if not dedented_str:
+            return
+
+        lines = dedented_str.splitlines()
+        string_list = StringList(lines, source="datatable_cell")
+
+        # Create temporary container node to hold nested parsed nodes
+        container = nodes.Element()
+        self.state.nested_parse(string_list, 0, container)
+
+        # Post-process container nodes to replace in-cell newlines with latex-safe
+        self._replace_cell_newlines(container)
+
+        # Transfer children from container to entry_node
+        for child in container.children:
+            entry_node += child
+
+    def _replace_cell_newlines(self, node: nodes.Node) -> None:
+        """Recursively replaces in-cell line breaks with raw break nodes.
+
+        WORKAROUND:
+            Sphinx's default LaTeXTranslator turns in-cell line break nodes into
+            '\\\\', which LaTeX interprets as a table row separator.
+
+        Args:
+            node: The docutils AST node to process recursively.
+        """
+        new_children: list[nodes.Node] = []
+        modified = False
+
+        for child in list(node.children):
+            if (
+                isinstance(child, nodes.raw)
+                and child.get("format") == "latex"
+                and child.astext().strip() in ("\\\\", r"\\")
+            ):
+                modified = True
+                latex_break = nodes.raw("", r"\newline ", format="latex")
+                latex_break.parent = node
+                new_children.append(latex_break)
+            elif isinstance(child, nodes.Text) and "\n" in child:
+                modified = True
+                parts = str(child).split("\n")
+                for i, part in enumerate(parts):
+                    clean_part = part.rstrip()
+                    if clean_part:
+                        t = nodes.Text(clean_part)
+                        t.parent = node
+                        new_children.append(t)
+                    if i < len(parts) - 1:
+                        latex_break = nodes.raw("", r"\newline ", format="latex")
+                        html_break = nodes.raw("", "<br/>", format="html")
+                        latex_break.parent = node
+                        html_break.parent = node
+                        new_children.extend([latex_break, html_break])
+            else:
+                self._replace_cell_newlines(child)
+                child.parent = node
+                new_children.append(child)
+
+        if modified:
+            node.children = new_children

sphinx_data2table-0.1.1/src/sphinx_data2table.egg-info/PKG-INFO

@@ -0,0 +1,12 @@
+Metadata-Version: 2.4
+Name: sphinx-data2table
+Version: 0.1.1
+Summary: Sphinx data-table extension for TOML, YAML, and JSON with Markdown cell parsing
+Author: jagarikokamukamu
+License-Expression: MIT
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pyyaml>=6.0.3
+Requires-Dist: sphinx>=8.0
+Dynamic: license-file

sphinx_data2table-0.1.1/src/sphinx_data2table.egg-info/SOURCES.txt

@@ -0,0 +1,11 @@
+LICENSE
+README.md
+pyproject.toml
+src/sphinx_data2table/__init__.py
+src/sphinx_data2table/directive.py
+src/sphinx_data2table.egg-info/PKG-INFO
+src/sphinx_data2table.egg-info/SOURCES.txt
+src/sphinx_data2table.egg-info/dependency_links.txt
+src/sphinx_data2table.egg-info/requires.txt
+src/sphinx_data2table.egg-info/top_level.txt
+tests/test_directive.py

sphinx_data2table-0.1.1/src/sphinx_data2table.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

sphinx_data2table-0.1.1/src/sphinx_data2table.egg-info/requires.txt

@@ -0,0 +1,2 @@
+pyyaml>=6.0.3
+sphinx>=8.0

sphinx_data2table-0.1.1/src/sphinx_data2table.egg-info/top_level.txt

@@ -0,0 +1 @@
+sphinx_data2table

sphinx_data2table-0.1.1/tests/test_directive.py

@@ -0,0 +1,231 @@
+"""Unit test suite for sphinx_data2table package and DataTableDirective."""
+
+from __future__ import annotations
+
+from unittest.mock import MagicMock
+
+from docutils import nodes
+from docutils.frontend import get_default_settings
+from docutils.parsers.rst import Parser, directives
+from docutils.utils import new_document
+
+from sphinx_data2table import __version__, setup
+from sphinx_data2table.directive import DataTableDirective
+
+
+def parse_rst_with_datatable(rst_content: str) -> nodes.document:
+    """Helper function to parse an RST string.
+
+    Args:
+        rst_content: RST string content.
+
+    Returns:
+        Docutils document AST.
+    """
+    directives.register_directive("data-table", DataTableDirective)
+    directives.register_directive("datatable", DataTableDirective)
+    parser = Parser()
+    settings = get_default_settings(Parser)  # type: ignore[arg-type]
+    doc = new_document("test.rst", settings)
+    parser.parse(rst_content, doc)
+    return doc
+
+
+def test_sphinx_extension_setup():
+    """Tests the Sphinx extension setup entry point function."""
+    mock_app = MagicMock()
+    metadata = setup(mock_app)
+
+    assert metadata["version"] == __version__
+    assert metadata["parallel_read_safe"] is True
+    assert metadata["parallel_write_safe"] is True
+    assert mock_app.add_directive.call_count == 2
+
+
+def test_json_inline_datatable():
+    """Tests parsing JSON inline content into a table."""
+    rst = """
+.. data-table::
+   :format: json
+
+   [
+     {"name": "**JSON Alpha**", "desc": "First item with `code`"},
+     {"name": "*JSON Beta*", "desc": "Second item"}
+   ]
+"""
+    doc = parse_rst_with_datatable(rst)
+    tables = list(doc.findall(nodes.table))
+    assert len(tables) == 1
+
+    table = tables[0]
+    thead = list(table.findall(nodes.thead))[0]
+    headers = [node.astext() for node in thead.findall(nodes.entry)]
+    assert headers == ["name", "desc"]
+
+    tbody = list(table.findall(nodes.tbody))[0]
+    rows = list(tbody.findall(nodes.row))
+    assert len(rows) == 2
+
+
+def test_yaml_inline_datatable():
+    """Tests parsing YAML inline content into a table."""
+    rst = """
+.. datatable::
+   :format: yaml
+
+   - name: "**Alpha**"
+     desc: "First item with `code`"
+   - name: "*Beta*"
+     desc: "Second item"
+"""
+    doc = parse_rst_with_datatable(rst)
+    tables = list(doc.findall(nodes.table))
+    assert len(tables) == 1
+
+    table = tables[0]
+    thead = list(table.findall(nodes.thead))[0]
+    headers = [node.astext() for node in thead.findall(nodes.entry)]
+    assert headers == ["name", "desc"]
+
+    tbody = list(table.findall(nodes.tbody))[0]
+    rows = list(tbody.findall(nodes.row))
+    assert len(rows) == 2
+
+
+def test_toml_inline_datatable():
+    """Tests parsing TOML inline content into a table."""
+    rst = """
+.. data-table::
+   :format: toml
+
+   [[items]]
+   name = "TOML Item 1"
+   val = "100"
+
+   [[items]]
+   name = "TOML Item 2"
+   val = "200"
+"""
+    doc = parse_rst_with_datatable(rst)
+    tables = list(doc.findall(nodes.table))
+    assert len(tables) == 1
+
+    table = tables[0]
+    tbody = list(table.findall(nodes.tbody))[0]
+    rows = list(tbody.findall(nodes.row))
+    assert len(rows) == 2
+
+
+def test_format_auto_detection():
+    """Tests format auto detection for JSON, TOML, and YAML."""
+    rst_json = """
+.. data-table::
+
+   [{"col": "val"}]
+"""
+    doc = parse_rst_with_datatable(rst_json)
+    assert len(list(doc.findall(nodes.table))) == 1
+
+    rst_yaml = """
+.. data-table::
+
+   - col: val
+"""
+    doc_y = parse_rst_with_datatable(rst_yaml)
+    assert len(list(doc_y.findall(nodes.table))) == 1
+
+
+def test_custom_headers_option():
+    """Tests custom :headers: option overriding dict keys."""
+    rst = """
+.. data-table::
+   :format: yaml
+   :headers: CustomA, CustomB
+
+   - key1: "Val1"
+     key2: "Val2"
+"""
+    doc = parse_rst_with_datatable(rst)
+    table = list(doc.findall(nodes.table))[0]
+    thead = list(table.findall(nodes.thead))[0]
+    headers = [node.astext() for node in thead.findall(nodes.entry)]
+    assert headers == ["CustomA", "CustomB"]
+
+
+def test_external_file_option(tmp_path):
+    """Tests reading data from external file via :file: option."""
+    yaml_file = tmp_path / "data.yaml"
+    yaml_file.write_text("- name: External\n  val: 42\n", encoding="utf-8")
+
+    rst = f"""
+.. data-table::
+   :file: {yaml_file}
+"""
+    doc = parse_rst_with_datatable(rst)
+    table = list(doc.findall(nodes.table))[0]
+    assert len(list(table.findall(nodes.row))) == 2
+
+
+def test_missing_file_error():
+    """Tests error handling for non-existent file."""
+    rst = """
+.. data-table::
+   :file: non_existent_file_path_xyz.yaml
+"""
+    doc = parse_rst_with_datatable(rst)
+    errors = list(doc.findall(nodes.system_message))
+    assert len(errors) > 0
+    assert "Could not read file" in errors[0].astext()
+
+
+def test_empty_content_and_file_error():
+    """Tests error handling when neither content nor :file: is provided."""
+    rst = """
+.. data-table::
+"""
+    doc = parse_rst_with_datatable(rst)
+    errors = list(doc.findall(nodes.system_message))
+    assert len(errors) > 0
+    assert "Neither content nor ':file:'" in errors[0].astext()
+
+
+def test_invalid_syntax_error():
+    """Tests error reporting when data contains invalid syntax."""
+    rst = """
+.. data-table::
+   :format: json
+
+   {invalid json content
+"""
+    doc = parse_rst_with_datatable(rst)
+    errors = list(doc.findall(nodes.system_message))
+    assert len(errors) > 0
+    assert "Failed to parse JSON" in errors[0].astext()
+
+
+def test_empty_data_warning():
+    """Tests warning generation when data parses to empty or invalid list."""
+    rst = """
+.. data-table::
+   :format: yaml
+
+   "just a string"
+"""
+    doc = parse_rst_with_datatable(rst)
+    warnings = list(doc.findall(nodes.system_message))
+    assert len(warnings) > 0
+    assert "Data is empty or invalid format" in warnings[0].astext()
+
+
+def test_in_cell_newline_replacement():
+    """Tests that in-cell newlines are replaced with format-safe break nodes."""
+    rst = """
+.. data-table::
+   :format: yaml
+
+   - col: "Line 1  \\nLine 2"
+"""
+    doc = parse_rst_with_datatable(rst)
+    raw_nodes = list(doc.findall(nodes.raw))
+    assert len(raw_nodes) >= 1
+    assert any(r.astext().strip() == r"\newline" for r in raw_nodes)