atelier.rstgen¶
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
================================ =============== ========
|
|
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
================================ =============== ========
|
|
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
================================ =============== ========
|
|
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 | | |
+--------------------+---------------+--------+
|
|
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. |