rstgen : Generating Sphinx docs

rstgen is a library of utilities to programmatically generate chunks of reStructuredText. It also contains a series of Sphinx extensions (in the rstgen.sphinxconf package).

We use it for making the docs for atelier, rstgen, etgen and lino.

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

The header(level, text) function

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
~~~~~~~

The table(headers, rows=tuple(), **kw) function

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():

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

Result:

Country

City

Name

Belgium

Eupen

Gerd

Estonia

Vigala

Luc

St. Vincent and the Grenadines

Chateaubelair

Nicole

A table without headers:

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

Result:

Belgium

Eupen

Gerd

Estonia

Vigala

Luc

St. Vincent and the Grenadines

Chateaubelair

Nicole

You might prefer to use directly the Table class:

>>> from 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
================================ =============== ========

Result:

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:

>>> 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 |               |        |
+--------------------+---------------+--------+

Result:

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

The srcref() function

Return the source file name of a module, for usage by Sphinx’s srcref role.

Example:

>>> from rstgen.utils import srcref
>>> import atelier
>>> print(srcref(atelier))
https://gitlab.com/lino-framework/atelier/blob/master/atelier/__init__.py

It doesn’t need to be the main package:

>>> from atelier.invlib import utils
>>> print(srcref(utils))
https://gitlab.com/lino-framework/atelier/blob/master/atelier/invlib/utils.py

The package must have an attribute SETUP_INFO, which must be a dict containing an item url And srcref() then assumes that SETUP_INFO['url'] is the base URL of the source repository.

For modules that don’t follow this convention, srcref() returns None.

>>> import pathlib
>>> print(srcref(pathlib))
None

Returns None if the source file is empty (which happens e.g. for __init__.py files whose only purpose is to mark a package).