atelier.rstgen

A library of utilities to programmatically generate chunks of reStructuredText. It is being used e.g. by the complextable directive and by the show method or a Lino request.

Kevin Horn wrote and maintains a comparable library, also called rstgen. (TODO: Check whether we should join our effords.)

(This module’s source code is available here.)

Functions

_test()

_write_header(writeln, level, s)

attrtable(rows, cols)

A shortcut for rendering a table showing the given attributes for each object.

boldheader(title)

Convert the given string into bold string, prefixed and followed by newlines.

header(level, text)

Render the text as a header with the specified level.

ol(items[, bullet])

Convert the given items into an ordered list.

table(headers[, rows])

Convert the given headers and rows into an reStructuredText formatted table.

toctree(*children, **options)

Return a toctree directive with specified options and children.

ul(items[, bullet])

Render the given items as a bullet list.`items` must be an iterable whose elements are strings..

write_header(fd, level, text)

Write the string text to file fd as a header of the given level.

Classes

Column(table, index, header[, width])

A column in a table.

Table(headers[, show_headers])

Used to render a table.

stdout_prefix(prefix)

class atelier.rstgen.Column(table, index, header, width=None)

Bases: object

A column in a table.

adjust_width(row)

Adjust required width of this column for the given row.

atelier.rstgen.header(level, text)

Render the text as a header with the specified level.

It uses and supposes the following system of header levels:

=======
Level 1
=======

-------
Level 2
-------

~~~~~~~
Level 3
~~~~~~~

Level 4
=======

Level 5
-------

Level 6
~~~~~~~
atelier.rstgen.write_header(fd, level, text)

Write the string text to file fd as a header of the given level. See header().

class atelier.rstgen.Table(headers, show_headers=True)

Bases: object

Used to render a table.

write(fd, data=[])

rstgen.table([‘header1’,’header2’]) no longer raises an exception “No rows in []” but renders a table with only headers and no rows.

atelier.rstgen.table(headers, rows=, **kw)

Convert the given headers and rows into an reStructuredText formatted table.

  • headers is an iterable of strings, one for each column

  • rows is an iterable of rows, each row being an iterable of strings.

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, []))

atelier.rstgen.ul(items, bullet='-')

Render the given items as a bullet list. items must be an iterable whose elements are strings.

If at least one item contains more than one paragraph, then all items are separated by an additional blank line.

>>> print(ul(["Foo", "Bar", "Baz"]))
- Foo
- Bar
- Baz

>>> print(ul([
...   "Foo", "An item\nwith several lines of text.", "Bar"]))
- Foo
- An item
  with several lines of text.
- Bar

>>> print(ul([
...   "A first item\nwith several lines of text.",
...   "Another item with a nested paragraph:\n\n  Like this.\n\nWow."]))

- A first item
  with several lines of text.

- Another item with a nested paragraph:

    Like this.

  Wow.
atelier.rstgen.ol(items, bullet='#.')

Convert the given items into an ordered list.

items must be an iterable whose elements are strings.

>>> print(ol(["Foo", "Bar", "Baz"]))
#. Foo
#. Bar
#. Baz

>>> print(ol([
...   "Foo", "An item\nwith several lines of text.", "Bar"]))
#. Foo
#. An item
   with several lines of text.
#. Bar

>>> print(ol([
...   "A first item\nwith several lines of text.",
...   "Another item with a nested paragraph:\n\n  Like this.\n\nWow."]))

#. A first item
   with several lines of text.

#. Another item with a nested paragraph:

     Like this.

   Wow.
atelier.rstgen.boldheader(title)

Convert the given string into bold string, prefixed and followed by newlines.

atelier.rstgen.toctree(*children, **options)

Return a toctree directive with specified options and children.

Usage examples

>>> toctree('a', 'b', 'c', maxdepth=2)
'\n\n.. toctree::\n    :maxdepth: 2\n\n    a\n    b\n    c\n'
>>> toctree('a', 'b', 'c', hidden=True)
'\n\n.. toctree::\n    :hidden:\n\n    a\n    b\n    c\n'
atelier.rstgen.attrtable(rows, cols)

A shortcut for rendering a table showing the given attributes for each object.

Arguments:

rows: an iterator of objects cols: a string with a space-separated list of attribute names