Metadata-Version: 2.4
Name: sphinx-tabular
Version: 0.2.4
Summary: Sphinx directives for CSV-powered tabular authoring.
Author: MAD2001
License-Expression: 0BSD
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.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Requires-Python: >=3.12
Description-Content-Type: text/markdown
License-File: LICENSE
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"
Requires-Dist: sphinx-design; extra == "dev"
Requires-Dist: sphinx-book-theme; 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"
Dynamic: license-file

# sphinx-tabular

[![PyPI](https://img.shields.io/pypi/v/sphinx-tabular.svg)](https://pypi.org/project/sphinx-tabular/)
[![Python](https://img.shields.io/pypi/pyversions/sphinx-tabular.svg)](https://pypi.org/project/sphinx-tabular/)
[![Docs](https://img.shields.io/badge/docs-GitHub%20Pages-blue)](https://deepthinker2001.github.io/sphinx-tabular/)
[![Downloads](https://img.shields.io/pepy/dt/sphinx-tabular.svg)](https://pypi.org/project/sphinx-tabular/)


[Full documentation](https://deepthinker2001.github.io/sphinx-tabular/index.html)

Instead of just modifying the final table output, `sphinx-tabular` builds real `docutils` table nodes (`table`/`tgroup`/`row`/`entry`) the same way `docutils`' own table directives do, and only overrides the HTML rendering of table cells (for colspan/rowspan/inline styling) — the rest of the output is generated by Sphinx's normal HTML writer.

While the table structure and merged cells will work in the LaTeX builder PDF output, the table formatting (colors, icons, bacgkround color, text color, and alignment) is HTML only.

## Donations to help support this project...

[Venmo](https://venmo.com/code?user_id=3950053597120230543&created=1783274674)


## Features

- Sphinx extension.
- Uses standard CSV files or native reStructuredText list-table syntax.
- Easily merge table cells with `<` and `^`.
- Support reStructuredText, rich reStructuredText list cells, 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.
- Sortable rows by clicking on the header row.
- Searchable option.

## Installation

`pip install sphinx-tabular`


### conf.py

```python
extensions = [
    ...,
    "sphinx_tabular",
    ...,
]
```

## Directives

### `rcsv-table`

Use CSV rows with reStructuredText cell content. Data may be inline or loaded
from an external `.rcsv` file.

```rst
.. rcsv-table:: Title
    :file: table.rcsv
```

### `mcsv-table`

Use CSV rows with MyST Markdown cell content. Data may be inline or loaded from
an external `.mcsv` file.

```rst
.. mcsv-table:: Title
    :file: table.mcsv
```

### `rlist-table`

Use a uniform two-level reStructuredText bullet list. Each top-level item is a
row, and each nested item is a cell. Rich reStructuredText nodes are preserved
inside ordinary cells.

```rst
.. rlist-table:: Interface status
    :header-rows: 1
    :stub-columns: 1

    * - Name
      - Owner
      - Status
    * - Alpha
      - **Able Team**
      - =STATUS(Ready; green)
```

`rlist-table` is inline-only. Use `.. include::` when the list should be kept
in another source file.


## Merging Cells

In `rcsv-table` and `mcsv-table`, an unquoted `<` merges with the cell to its
left and an unquoted `^` merges with the cell above it.

```rst
.. rcsv-table:: Horizontal merge

    Merged,<
    Unmerged,Unmerged
```

```rst
.. rcsv-table:: Vertical merge

    Merged,Unmerged
    ^,Unmerged
```

In `rlist-table`, a cell containing one plain-text `<` or `^` is a merge
marker. Use an inline literal such as `` `<` `` or `` `^` `` when the
character should be displayed instead.

```rst
.. rlist-table:: List merge

    * - Merged
      - <
    * - Unmerged
      - Unmerged
```


## Options

Supported options include:

- `:align:` Place an `rlist-table` at `left`, `center`, or `right`.
- `:class:` Additional classes to add to the table.
- `:file:` Path to the `.rcsv` or `.mcsv` file. Not supported by `rlist-table`.
- `:header-rows:` Number of top rows to format as header rows. If `:sticky-header:` is set, these rows become sticky.
- `:initial-sort:` Apply independent page-load ordering using one-based `COLUMN=TYPE[:reverse]` criteria.
- `:name:` Assign an explicit target name to an `rlist-table`.
- `:search:` Add a search field with a row count to the table and enable searching.
- `:sortable:` Enable row sorting by clicking on the headers.
- `:sort-types:` Assign interactive sort types using one-based `COLUMN=TYPE` entries.
- `:sticky-header:` Make the header rows sticky when scrolling long tables.
- `:sticky-offset:`  CSS offset for sticky headers, such as `3.5rem`.
- `:strict:`  Treat ragged rows and malformed input as errors instead of warnings.
- `:stub-columns:` Mark leftmost columns as semantic stubs for `rlist-table`.
- `:text-align:` Horizontal alignment of text in the cells. Default is `left`.
- `:vertical-align:` Vertical alignment of text in cells. Default is `middle`.
- `:width:` CSS width for the table, such as `100%`.
- `:widths:` A space-separated list of column widths.


## Formatting

* Custom theming.
* `=ALIGN()` horizontal/vertical cell value alignment.
* `=BG()` set the background cell color.
* `=FG()` set text color.
* `=ICON()` use a Font Awesome or Bootstrap icon, or a fallback.
* `=STATUS()` insert a colored status pill.


## Spreadsheet

* `'` interprest as literal text without evaluation.
* `+`,`-`,`*`,`/` arithmetic operations on cells.
* `=C4` cell references.
* `=A4:B4` cell ranges.
* `=AVG()` take the average.
* `=CONCAT()` concatenation of cell values.
* `=COUNT()` count number of numerical values.
* `=IF()` conditional evaluation.
* `=MAX()` find the maximum value.
* `=MIN()` find the minimum value.
* `=ROUND()` round the number to an int or the specified decimal places.
* `=SUM()` sum a set or range of values.


