atelier.rstgen

(source code)

A suite of utilities to programmatically generate chunks of reStructuredText.

Especially the table() function is used by the complextable directive and by Table.to_rst. Here we present the raw API.

Usage examples

Here is the data we are going to render into different tables:

>>> headers = ["Country", "City", "Name"]
>>> rows = []
>>> rows.append(["Belgium","Eupen","Gerd"])
>>> rows.append(["Estonia","Vigala","Luc"])
>>> rows.append(["St. Vincent and the Grenadines","Chateaubelair","Nicole"])

The simplest case of table():

Code Result
>>> from atelier.rstgen import table
>>> print(table(headers,rows))
================================ =============== ========
 Country                          City            Name
-------------------------------- --------------- --------
 Belgium                          Eupen           Gerd
 Estonia                          Vigala          Luc
 St. Vincent and the Grenadines   Chateaubelair   Nicole
================================ =============== ========

Country City Name
Belgium Eupen Gerd
Estonia Vigala Luc
St. Vincent and the Grenadines Chateaubelair Nicole

A table without headers:

Code Result
>>> print(table(headers,rows,show_headers=False))
================================ =============== ========
 Belgium                          Eupen           Gerd
 Estonia                          Vigala          Luc
 St. Vincent and the Grenadines   Chateaubelair   Nicole
================================ =============== ========

Belgium Eupen Gerd
Estonia Vigala Luc
St. Vincent and the Grenadines Chateaubelair Nicole

You might prefer to use directly the Table class:

Code Result
>>> from atelier.rstgen import Table
>>> t = Table(headers)
>>> print(t.to_rst(rows))
================================ =============== ========
 Country                          City            Name
-------------------------------- --------------- --------
 Belgium                          Eupen           Gerd
 Estonia                          Vigala          Luc
 St. Vincent and the Grenadines   Chateaubelair   Nicole
================================ =============== ========

Country City Name
Belgium Eupen Gerd
Estonia Vigala Luc
St. Vincent and the Grenadines Chateaubelair Nicole

If there is at least one cell that contains a newline character, the result will be a complex table:

Code Result
>>> rows[2] = ['''St. Vincent
... and the Grenadines''',"Chateaubelair","Nicole"]
>>> print(table(headers,rows))
+--------------------+---------------+--------+
| Country            | City          | Name   |
+====================+===============+========+
| Belgium            | Eupen         | Gerd   |
+--------------------+---------------+--------+
| Estonia            | Vigala        | Luc    |
+--------------------+---------------+--------+
| St. Vincent        | Chateaubelair | Nicole |
| and the Grenadines |               |        |
+--------------------+---------------+--------+

Country City Name
Belgium Eupen Gerd
Estonia Vigala Luc
St. Vincent and the Grenadines Chateaubelair Nicole

Empty tables

A special case is a table with no rows. For table(headers, []) the following output would be logical:

========= ====== ======
 Country   City   Name
--------- ------ ------
========= ====== ======

But Sphinx would consider this a malformed table. That’s why we return a blank line when there are no rows:

>>> print(table(headers, []))

Functions

boldheader(title)
header(level, text) Render the text as a header with the specified level.
ol(items[, bullet])
>>> print(ol(["Foo", "Bar", "Baz"]))
table(headers[, rows])
ul(items[, bullet]) Render the given items as a bullet list <http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html#bullet-lists>.
write_header(fd, level, s)

Classes

Column(table, index, header[, width]) A column in a table.
Table(headers[, show_headers]) Renders as a table.