`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.

>>> from rstgen import *

Headers ¶

rstgen.header(level, text)¶

Render the text as a header with the specified level.

It uses and assumes the following system of header levels:

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

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

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

Level 4
=======

Level 5
-------

Level 6
~~~~~~~

Tables ¶

rstgen.table(headers, rows=tuple(), **kw)¶

Render the given headers and rows as 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 use case of table():

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

You can get the same result by using the Table class directly:

>>> t = Table(headers)
>>> print(t.to_rst(rows))
================================ =============== ========
 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
================================ =============== ========

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

>>> rows[2][0] = "St. Vincent\nand the Grenadines"
>>> 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, []))

Bullet lists ¶

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.

Ordered lists ¶

rstgen.ol(items, bullet='#.')¶: Render the given items as an ordered (numbered) 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.

Miscellaneous ¶

rstgen.boldheader(title)¶: Render the given text as a bold string, prefixed and followed by newlines.

rstgen.attrtable(rows, cols)¶

Render the attributes of each object to a table.

Arguments:

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

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'

Link to the source code ¶

Return the source file name of a Python module, for usage by the 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).

Configuration settings ¶

The rstgen module provides the following configuration settings:

public_url¶: The canonical public URL where this website is to be published.

use_dirhtml¶: Whether sphinx-build should use dirhtml instead of the default html builder.

selectable_languages¶

A tuple or list of language codes for which there is a doctree.

It is used to build multilingual websites. Caution: this is tricky.

The first specified language is the default language, whose source tree is docs. For every remaining language xx there must be a source tree named xxdocs. These non-default source trees will be built below the default source tree.

When selectable_languages is [‘en’, ‘de’] and doc_trees has its default value [‘docs’], then atelier expects two Sphinx source trees docs and dedocs. The output of docs will be under the normal location docs/.build, but the output of dedocs will be under docs/.build/de.

rstgen.set_config_var(**kwargs)¶

rstgen.get_config_var(k)¶

class rstgen.Table¶

The object used by table() when rendering a table.

write(self, fd, data=[])¶: Write this table to the specified stream fd.

to_rst()¶: Return this table as a string in reSTructuredText format.

rstgen : Generating Sphinx docs¶

`rstgen` : Generating Sphinx docs¶