Metadata-Version: 1.1
Name: rstgen
Version: 20.7.1
Summary: Generate rst chunks from Python objects.
Home-page: UNKNOWN
Author: Luc Saffre
Author-email: luc.saffre@gmail.com
License: BSD-2-Clause
Description: =====================
        The ``rstgen`` module
        =====================
        
        rstgen is a library of utilities to programmatically generate chunks of
        `reStructuredText <http://docutils.sourceforge.net/rst.html>`__.  It is being
        used e.g. by `atelier`, `etgen` and `lino`.
        
        Kevin Horn wrote and maintains a comparable library, also called
        `rstgen <https://bitbucket.org/khorn/rstgen/src>`_. (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.
        
        .. rubric:: 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        | Chateaubelair | Nicole |
        | and the Grenadines |               |        |
        +--------------------+---------------+--------+
        
        
        .. rubric:: 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>
        
Platform: UNKNOWN
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: BSD License
Classifier: Natural Language :: English
Classifier: Operating System :: OS Independent
