Skip to main content

Pythonic API for generating reStructuredText.

Project description

rstgen is a library of utilities to programmatically generate chunks of reStructuredText. It is being used e.g. by atelier, etgen and lino.

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

Source code: https://github.com/lino-framework/rstgen

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

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

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

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

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

The srcref() function

Return the source file name of a module, for usage by Sphinx’s srcref role. Returns None if the source file is empty (which happens e.g. for __init__.py files whose only purpose is to mark a package).

Examples:

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

The module must have an attribute SETUP_INFO, which must be a dict containing an item url If it doesn’t, srcref() returns None. Otherwise srcref() assumes that SETUP_INFO['url'] is the base URL of the source repository.

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

Changelog

2021-03-06 Use pathlib instead of unipath 2022-05-24 Moved some utility functions from atelier.utils to rstgen.utils

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

rstgen-22.5.0.tar.gz (22.9 kB view hashes)

Uploaded Source

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page