Metadata-Version: 2.4
Name: sphinx-tabular
Version: 0.2.1
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"
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 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
```

Markdown, external file:

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

Markdown, 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
```


## Additional Capabilities

See [full documentation](https://deepthinker2001.github.io/sphinx-tabular/) for additional capabilities:

### 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.


