sphinx-tabular 0.1.0__tar.gz

sphinx_tabular-0.1.0/PKG-INFO

@@ -0,0 +1,127 @@
+Metadata-Version: 2.4
+Name: sphinx-tabular
+Version: 0.1.0
+Summary: Sphinx directives for CSV-powered tabular authoring.
+Author: Your Name
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/deepthinker2001/sphinx-tabular
+Project-URL: Documentation, https://deepthinker2001.github.io/sphinx-tabular/
+Project-URL: Repository, https://github.com/deepthinker2001/sphinx-tabular
+Project-URL: Issues, https://github.com/deepthinker2001/sphinx-tabular/issues
+Keywords: sphinx,documentation,csv,tables,restructuredtext,myst
+Classifier: Development Status :: 3 - Alpha
+Classifier: Framework :: Sphinx
+Classifier: Framework :: Sphinx :: Extension
+Classifier: Intended Audience :: Developers
+Classifier: Topic :: Documentation
+Classifier: Topic :: Documentation :: Sphinx
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+Requires-Dist: sphinx>=9.1
+Requires-Dist: docutils>=0.20
+Requires-Dist: myst-parser>=5
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: build; extra == "dev"
+Requires-Dist: twine; extra == "dev"
+Provides-Extra: docs
+Requires-Dist: sphinx>=9.1; python_version >= "3.12" and extra == "docs"
+Requires-Dist: sphinx-book-theme; extra == "docs"
+Requires-Dist: sphinx-design>=0.7.0; extra == "docs"
+
+# sphinx-tabular
+
+## Features
+
+- Sphinx extension.
+- Uses standard CSV file format.
+- Easily merge table cells with `<` and `^`.
+- Support reStructuredText and Markdown.
+- Support for inline table data and external files.
+- Optional sticky header support for one or more header rows.
+- Provides a minimal set of spreadsheet formulas.
+- Set table cell alignment and per-cell alignment in both horizontal and vertical directions.
+- Set custom cell text and background colors.
+- Custom status pill.
+- Support for Font Awesome and Bootstrip icons if installed by your theme.
+
+
+
+# Installation
+
+`pip install sphinx-tabular`
+
+
+# conf.py
+
+```bash
+extensions = [
+    ...,
+    'sphinx_tabular',
+    ...,
+]
+```
+
+## Directives
+
+RST, external file:
+
+```RST
+.. rcsv-table:: Title
+    :file: table.rcsv
+```
+
+RST, inline data.
+
+```RST
+.. rcsv-table:: Title
+
+    Col 1, Row 1
+    Col 2, Row 2
+```
+
+MD, external file:
+
+```RST
+.. rcsv-table:: Title
+    :file: table.rcsv
+```
+
+MD, inline data.
+
+```RST
+.. rcsv-table:: Title
+
+    Col 1, Row 1
+    Col 2, Row 2
+```
+
+
+## Merging Cells
+
+Columns
+
+```RST
+.. rcsv-table:: Title
+
+    Merged,<
+    Unmerged, Unmerged
+```
+
+Rows
+
+```RST
+.. rcsv-table:: Title
+
+    Merged,Unmerged
+    ^, Unmerged
+```
+
+
+
+

sphinx_tabular-0.1.0/README.md

@@ -0,0 +1,91 @@
+# sphinx-tabular
+
+## Features
+
+- Sphinx extension.
+- Uses standard CSV file format.
+- Easily merge table cells with `<` and `^`.
+- Support reStructuredText and Markdown.
+- Support for inline table data and external files.
+- Optional sticky header support for one or more header rows.
+- Provides a minimal set of spreadsheet formulas.
+- Set table cell alignment and per-cell alignment in both horizontal and vertical directions.
+- Set custom cell text and background colors.
+- Custom status pill.
+- Support for Font Awesome and Bootstrip icons if installed by your theme.
+
+
+
+# Installation
+
+`pip install sphinx-tabular`
+
+
+# conf.py
+
+```bash
+extensions = [
+    ...,
+    'sphinx_tabular',
+    ...,
+]
+```
+
+## Directives
+
+RST, external file:
+
+```RST
+.. rcsv-table:: Title
+    :file: table.rcsv
+```
+
+RST, inline data.
+
+```RST
+.. rcsv-table:: Title
+
+    Col 1, Row 1
+    Col 2, Row 2
+```
+
+MD, external file:
+
+```RST
+.. rcsv-table:: Title
+    :file: table.rcsv
+```
+
+MD, inline data.
+
+```RST
+.. rcsv-table:: Title
+
+    Col 1, Row 1
+    Col 2, Row 2
+```
+
+
+## Merging Cells
+
+Columns
+
+```RST
+.. rcsv-table:: Title
+
+    Merged,<
+    Unmerged, Unmerged
+```
+
+Rows
+
+```RST
+.. rcsv-table:: Title
+
+    Merged,Unmerged
+    ^, Unmerged
+```
+
+
+
+

sphinx_tabular-0.1.0/pyproject.toml

@@ -0,0 +1,69 @@
+[build-system]
+requires = ["setuptools>=69", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "sphinx-tabular"
+version = "0.1.0"
+description = "Sphinx directives for CSV-powered tabular authoring."
+readme = "README.md"
+requires-python = ">=3.12"
+license = "MIT"
+authors = [
+  { name = "Your Name" }
+]
+keywords = [
+  "sphinx",
+  "documentation",
+  "csv",
+  "tables",
+  "restructuredtext",
+  "myst",
+]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Framework :: Sphinx",
+  "Framework :: Sphinx :: Extension",
+  "Intended Audience :: Developers",
+  "Topic :: Documentation",
+  "Topic :: Documentation :: Sphinx",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Programming Language :: Python :: 3.14",
+]
+
+dependencies = [
+  "sphinx>=9.1",
+  "docutils>=0.20",
+  "myst-parser>=5",
+]
+
+[project.optional-dependencies]
+dev = [
+  "pytest",
+  "build",
+  "twine",
+]
+
+docs = [
+  "sphinx>=9.1; python_version >= '3.12'",
+  "sphinx-book-theme",
+  "sphinx-design>=0.7.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/deepthinker2001/sphinx-tabular"
+Documentation = "https://deepthinker2001.github.io/sphinx-tabular/"
+Repository = "https://github.com/deepthinker2001/sphinx-tabular"
+Issues = "https://github.com/deepthinker2001/sphinx-tabular/issues"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+sphinx_tabular = ["static/*.css", "static/*.js"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

sphinx_tabular-0.1.0/setup.cfg

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

sphinx_tabular-0.1.0/src/sphinx_tabular/__init__.py

@@ -0,0 +1,42 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+from .directive import McsvTableDirective, RcsvTableDirective
+
+from docutils import nodes
+
+from .html import depart_entry_html, visit_entry_html
+
+def setup(app):
+    # Needed for .mcsv cell parsing.
+    app.setup_extension("myst_parser")
+
+    app.add_directive("rcsv-table", RcsvTableDirective)
+    app.add_directive("mcsv-table", McsvTableDirective)
+
+    app.add_node(
+        nodes.entry,
+        override=True,
+        html=(visit_entry_html, depart_entry_html),
+    )
+
+    app.add_config_value("sphinx_tabular_strict", False, "env")
+
+    app.connect("builder-inited", _copy_static_assets)
+    app.add_css_file("sphinx-tabular.css")
+    app.add_js_file("sphinx-tabular.js")
+
+    return {
+        "version": "0.1.0",
+        "parallel_read_safe": True,
+        "parallel_write_safe": True,
+    }
+
+
+    
+
+def _copy_static_assets(app):
+    static_src = Path(__file__).parent / "static"
+    if str(static_src) not in app.config.html_static_path:
+        app.config.html_static_path.append(str(static_src))

sphinx_tabular-0.1.0/src/sphinx_tabular/directive.py

@@ -0,0 +1,148 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+from docutils.parsers.rst import directives
+from sphinx.errors import ExtensionError
+from sphinx.util.docutils import SphinxDirective
+
+from .normalize import normalize_rows
+from .parser import RcsvParseError, parse_csv_with_quote_tracking
+from .render_nodes import build_table_node
+from docutils import nodes
+from sphinx.util import logging
+
+logger = logging.getLogger(__name__)
+
+class BaseTabularDirective(SphinxDirective):
+    has_content = True
+    required_arguments = 0
+    optional_arguments = 1
+    final_argument_whitespace = True
+
+    markup = "rst"
+    directive_name = "tabular-table"
+    dialect_class = "sphinx-tabular"
+
+    option_spec = {
+        "file": directives.unchanged_required,
+        "header-rows": directives.nonnegative_int,
+        "width": directives.unchanged,
+        "widths": directives.unchanged,
+        "class": directives.class_option,
+        "text-align": directives.unchanged,
+        "vertical-align": directives.unchanged,
+        "sticky-header": directives.flag,
+        "sticky-offset": directives.unchanged,
+        "strict": directives.flag,
+    }
+    def _is_strict(self) -> bool:
+        return bool(
+            "strict" in self.options
+            or getattr(self.config, "sphinx_tabular_strict", False)
+        )
+
+
+    def _warn_or_raise(self, message: str) -> list[nodes.Node]:
+        if self._is_strict():
+            raise ExtensionError(message)
+
+        source, line = self.get_source_info()
+
+        logger.warning(
+            "sphinx-tabular: %s",
+            message,
+            location=(source, line),
+        )
+
+        return []
+    
+    def run(self):
+        caption = self.arguments[0] if self.arguments else None
+
+        has_file = "file" in self.options
+        has_inline_content = any(line.strip() for line in self.content)
+
+        strict = bool(
+            "strict" in self.options
+            or getattr(self.config, "sphinx_tabular_strict", False)
+        )
+
+        if has_file and has_inline_content:
+            return self._warn_or_raise(
+                f"{self.directive_name}: specify either :file: or inline content, not both"
+            )
+
+        if not has_file and not has_inline_content:
+            return self._warn_or_raise(
+                f"{self.directive_name}: specify either :file: or inline content"
+            )
+
+        if has_file:
+            rel_file = self.options["file"]
+
+            doc_dir = Path(self.env.doc2path(self.env.docname)).parent
+            source_path = (doc_dir / rel_file).resolve()
+
+            if not source_path.exists():
+                return self._warn_or_raise(
+                    f"{self.directive_name}: file not found: {rel_file}"
+                )
+
+            self.env.note_dependency(str(source_path))
+            text = source_path.read_text(encoding="utf-8")
+            source = str(source_path)
+        else:
+            text = "\n".join(self.content)
+            source = self.env.doc2path(self.env.docname)
+
+
+        try:
+            raw_rows = parse_csv_with_quote_tracking(text)
+            rows = normalize_rows(
+                raw_rows,
+                source=source,
+                strict=strict,
+                directive_name=self.directive_name,
+                warning_docname=self.env.docname,
+                warning_line_offset=self.content_offset - 1,
+            )
+        except RcsvParseError as exc:
+            return self._warn_or_raise(f"{self.directive_name}: {exc}")
+        except ValueError as exc:
+            return self._warn_or_raise(f"{self.directive_name}: {exc}")
+
+        classes = [
+            "sphinx-tabular",
+            self.dialect_class,
+        ]
+        classes.extend(self.options.get("class", []))
+
+        if "sticky-header" in self.options:
+            classes.append("sphinx-tabular-sticky-header")
+
+        table = build_table_node(
+            rows,
+            directive=self,
+            source=source,
+            markup=self.markup,
+            caption=caption,
+            header_rows=self.options.get("header-rows", 0),
+            table_classes=classes,
+            table_width=self.options.get("width"),
+            sticky_offset=self.options.get("sticky-offset"),
+        )
+
+        return [table]
+
+
+class RcsvTableDirective(BaseTabularDirective):
+    markup = "rst"
+    directive_name = "rcsv-table"
+    dialect_class = "sphinx-tabular-rcsv"
+
+
+class McsvTableDirective(BaseTabularDirective):
+    markup = "myst"
+    directive_name = "mcsv-table"
+    dialect_class = "sphinx-tabular-mcsv"