rst-table-span 1.0.0__py2.py3-none-any.whl

rst_table_span-1.0.0.dist-info/METADATA

@@ -0,0 +1,158 @@
+Metadata-Version: 2.4
+Name: rst-table-span
+Version: 1.0.0
+Summary: Support for colspan and rowspan in RST tables for docutils and Sphinx
+Author-email: Rasmus Bondesson <raek@raek.se>
+Description-Content-Type: text/x-rst
+License-Expression: MIT
+License-File: LICENSE
+Requires-Dist: docutils
+Project-URL: Home, https://github.com/raek/rst-table-span/
+
+**************
+rst-table-span
+**************
+
+reStructuredText provides four syntaxes for tables:
+
+* Grid tables
+* Simple tables
+* List tables
+* CSV tables
+
+However, only grid and simple tables support cells spanning multiple columns, and only
+grid tables support cells spanning multiple rows.
+
+The ``rst-table-span`` package adds the ``:colspan:`C```, ``:rowspan:`R```, and
+``:cellspan:`CxR``` roles which add support for column and row span *to all
+existing RST table types*.
+
+This project was inspired by the ``flat-table`` directive from the LinuxDoc_ project.
+
+.. _LinuxDoc: https://return42.github.io/linuxdoc/linuxdoc-howto/table-markup.html#flat-table
+
+
+Example
+=======
+
+To produce a table like this:
+
+.. table::
+
+   +------------------------+------------+----------+----------+
+   | Header row, column 1   | Header 2   | Header 3 | Header 4 |
+   | (header rows optional) |            |          |          |
+   +========================+============+==========+==========+
+   | body row 1, column 1   | column 2   | column 3 | column 4 |
+   +------------------------+------------+----------+----------+
+   | body row 2             | Cells may span columns.          |
+   +------------------------+------------+---------------------+
+   | body row 3             | Cells may  | Corner              |
+   +------------------------+ span rows. |                     |
+   | body row 4             |            |                     |
+   +------------------------+------------+---------------------+
+
+You would normally need to write this::
+
+   +------------------------+------------+----------+----------+
+   | Header row, column 1   | Header 2   | Header 3 | Header 4 |
+   | (header rows optional) |            |          |          |
+   +========================+============+==========+==========+
+   | body row 1, column 1   | column 2   | column 3 | column 4 |
+   +------------------------+------------+----------+----------+
+   | body row 2             | Cells may span columns.          |
+   +------------------------+------------+---------------------+
+   | body row 3             | Cells may  | Corner              |
+   +------------------------+ span rows. |                     |
+   | body row 4             |            |                     |
+   +------------------------+------------+---------------------+
+
+But with ``rst-table-span`` you can instead write it using a ``csv-table``::
+
+   .. csv-table::
+      :header-rows: 1
+
+      "Header row, column 1 (header rows optional)", Header 2, Header 3, Header 4
+      "body row 1, column 1", column 2, column 3, column 4
+      body row 2, :colspan:`3` Cells may span columns.
+      body row 3, :rowspan:`2` Cells may span rows., :cellspan:`2x2` Corner
+      body row 4
+
+Or a ``list-table``::
+
+   .. list-table::
+      :header-rows: 1
+
+      * - Header row, column 1 (header rows optional)
+        - Header 2
+        - Header 3
+        - Header 4
+      * - body row 1, column 1
+        - column 2
+        - column 3
+        - column 4
+      * - body row 2
+        - :colspan:`3` Cells may span columns.
+        -
+        -
+      * - body row 3
+        - :rowspan:`2` Cells may span rows.
+        - :cellspan:`2x2` Corner
+        -
+      * - body row 4
+        -
+        -
+        -
+
+
+Installation and Usage
+======================
+
+Install the package using pip::
+
+   pip install rst-table-span
+
+or add the ``rst-table-span`` package to your project or environment dependency
+list (eg. ``pyproject.toml``, ``requirements.txt``, or similar).
+
+
+Sphinx
+------
+
+Also add the ``rst_table_span`` module to your list of extensions in your
+``conf.py`` settings::
+
+   extensions = [
+       "rst_table_span",
+   ]
+
+
+Docutils
+--------
+
+.. _Publisher API: https://docutils.sourceforge.io/docs/api/publisher.html
+
+Docutils doesn't provide a declarative extension mechanism, as far as I know. If
+you invoke docutils programatically using its `Publisher API`_, then a global
+function is provided to register the roles. Call it before setting up the publisher::
+
+   import sys
+   import docutils.__main__
+   import rst_table_span
+
+   rst_table_span.register_docutils_roles()
+   sys.exit(docutils.__main__.main())
+
+For convenience, this package installs the above script as the
+``rst-table-span-docutils`` executable. It behaves the same way as the standard
+``docutils`` executable. It can then be used used like this::
+
+   rst-table-span-docutils demo.rst --output demo.html
+
+
+License
+=======
+
+This library is released under the **MIT license** (see the ``LICENSE`` file in
+the source code).
+

rst_table_span-1.0.0.dist-info/RECORD

@@ -0,0 +1,6 @@
+rst_table_span.py,sha256=WMsZwcn2sacCdfd965PugW0HK-fnkEAf9IwfcYqo_i0,4514
+rst_table_span-1.0.0.dist-info/entry_points.txt,sha256=PNjJhz6QNvj8ht8DkbRRNphzCXvQ0i3aOqAHBzpKu2U,63
+rst_table_span-1.0.0.dist-info/licenses/LICENSE,sha256=5ksw4CA6YRYGt6P84r-wnq67GOhydQm9NHvVtOJ1MMQ,1083
+rst_table_span-1.0.0.dist-info/WHEEL,sha256=Dyt6SBfaasWElUrURkknVFAZDHSTwxg3PaTza7RSbkY,100
+rst_table_span-1.0.0.dist-info/METADATA,sha256=bDw_Kqj0m2ic_KnyjtTELA0N_LqFZiS_6vxDycrTRHE,4889
+rst_table_span-1.0.0.dist-info/RECORD,,

rst_table_span-1.0.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: flit 3.12.0
+Root-Is-Purelib: true
+Tag: py2-none-any
+Tag: py3-none-any

rst_table_span-1.0.0.dist-info/entry_points.txt

@@ -0,0 +1,3 @@
+[console_scripts]
+rst-table-span-docutils=rst_table_span:main
+

rst_table_span-1.0.0.dist-info/licenses/LICENSE

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

rst_table_span.py

@@ -0,0 +1,127 @@
+"""Support for colspan and rowspan in RST tables for docutils and Sphinx"""
+
+__version__ = "1.0.0"
+
+
+import re
+
+import docutils.nodes as nodes
+from docutils.transforms import Transform, TransformError
+
+
+def col_span_role(role, rawtext, text, lineno, inliner, options=None, content=None):
+    if not text.isnumeric() or int(text) < 1:
+        return None, [inliner.reporter.error("colspan must be a positive integer", line=lineno)]
+    return make_pending_nodes(inliner, int(text), 1)
+
+
+def row_span_role(role, rawtext, text, lineno, inliner, options=None, content=None):
+    if not text.isnumeric() or int(text) < 1:
+        return None, [inliner.reporter.error("colspan must be a positive integer", line=lineno)]
+    return make_pending_nodes(inliner, 1, int(text))
+
+
+def cell_span_role(role, rawtext, text, lineno, inliner, options=None, content=None):
+    m = re.match(r"(?P<cols>[1-9][0-9]*)x(?P<rows>[1-9][0-9]*)", text)
+    if not m:
+        return None, [inliner.reporter.error("cellspan must be of format <COLS>x<ROWS>", line=lineno)]
+    return make_pending_nodes(inliner, int(m.group("cols")), int(m.group("rows")))
+
+
+def make_pending_nodes(inliner, cols, rows):
+    details = dict(cols=cols, rows=rows)
+    mark = nodes.pending(CellSpanMarkTransform, details)
+    inliner.document.note_pending(mark)
+    sweep = nodes.pending(CellSpanSweepTransform)
+    inliner.document.note_pending(sweep)
+    return [mark, sweep], []
+
+
+class CellSpanMarkTransform(Transform):
+    default_priority = 213
+
+    def apply(self):
+        col_span = self.startnode.details["cols"]
+        row_span = self.startnode.details["rows"]
+        cell_node = pop_pending_and_find_cell(self.startnode)
+        row_node = cell_node.parent
+        table_node = row_node.parent
+        col_index = row_node.children.index(cell_node)
+        row_index = table_node.children.index(row_node)
+        if col_index + col_span > len(row_node.children):
+            raise TransformError("colspan extending outside table")
+        if row_index + row_span > len(table_node.children):
+            raise TransformError("colspan extending outside table")
+
+        table_node["needs_sweep"] = True
+        for i in range(row_span):
+            loop_row = table_node.children[row_index + i]
+            for j in range(col_span):
+                loop_cell = loop_row.children[col_index + j]
+                if i == 0 and j == 0:
+                    # The top left cell of the span rectangle contains the
+                    # contents. Keep it and set its "more" attributes.
+                    loop_cell["morecols"] = col_span - 1
+                    loop_cell["morerows"] = row_span - 1
+                else:
+                    # Other cells in the span rectangle shall be removed.
+                    loop_cell["sweep"] = True
+
+
+class CellSpanSweepTransform(Transform):
+    default_priority = 214
+
+    def apply(self):
+        cell_node = pop_pending_and_find_cell(self.startnode)
+        row_node = cell_node.parent
+        table_node = row_node.parent
+
+        if not table_node.attributes.get("needs_sweep", False):
+            return
+        for row in table_node.children:
+            to_sweep = [entry for entry in row.children
+                        if entry.attributes.get("sweep", False)]
+            for entry in to_sweep:
+                row.children.remove(entry)
+        del table_node.attributes["needs_sweep"]
+
+
+def pop_pending_and_find_cell(pending):
+    node = pending.parent
+    pending.parent.remove(pending)
+    while True:
+        if node is None:
+            raise TransformError("colspan, rowspan, and cellspan roles must be used in table cells")
+        elif isinstance(node, nodes.entry):
+            break
+        else:
+            node = node.parent
+    return node
+
+
+# Entrypoint for the Sphinx extension mechanism
+def setup(app):
+    app.add_role("colspan", col_span_role)
+    app.add_role("rowspan", row_span_role)
+    app.add_role("cellspan", cell_span_role)
+
+    return {
+        "version": __version__,
+        "parallel_read_safe": True,
+        "parallel_write_safe": True,
+    }
+
+
+# Entrypoint for docutils-style command line utility
+def main():
+    import sys
+    from docutils.__main__ import main
+    register_docutils_roles()
+    sys.exit(main())
+
+
+def register_docutils_roles():
+    from docutils.parsers.rst import roles
+    roles.register_canonical_role("colspan", col_span_role)
+    roles.register_canonical_role("rowspan", row_span_role)
+    roles.register_canonical_role("cellspan", cell_span_role)