`cape.tnakit.rstutils`: Tools for writing ReST files¶

This module contains tools to write text formatted for reStructuredText (reST). This includes various markup options and tools for creating the directives to include images. Of particular interest are the functions rst_image_table_lines() and rst_image_table(), which simplifies the important task of creating a table that includes several images.

cape.tnakit.rstutils.py2rst(v, **kw)¶

Convert a generic Python object to reST text

Call:

>>> txt = py2rst(v, **kw)

Inputs:

v: object: Generic Python value
repr_types: {None} | type | tuple: Type or tuple of types for which to use repr()
str_types: {None} | type | tuple: Type or tuple of types for which to use str()
strict: {True} | False: Whether or not to raise exception for other types

Outputs:

txt: str: Marked up reST text

Versions:

2019-04-25 @ddalle: Version 1.0

cape.tnakit.rstutils.py2rst_any_repr(v, markup=True)¶

Convert a Python to reST text using repr()

Call:

>>> txt = py2rst_any_repr(v, markup=True)

Inputs:

v: any: Quantity to convert using repr()
markup: {True} | False: Whether or not to add backticks around converted text

Outputs:

txt: str: Text representation for reST

Versions:

2019-04-25 @ddalle: Version 1.0

cape.tnakit.rstutils.py2rst_any_str(v, markup=True)¶

Convert a Python to reST text using str()

Call:

>>> txt = py2rst_any_str(v, markup=True)

Inputs:

v: any: Quantity to convert using repr()
markup: {True} | False: Whether or not to add backticks around converted text

Outputs:

txt: str: Text representation for reST

Versions:

2019-04-25 @ddalle: Version 1.0

cape.tnakit.rstutils.py2rst_bool(q, markup=True)¶

Convert a Python bool to reST text

Call:

>>> txt = py2rst_bool(q, markup=True)

Inputs:

q: True | False | bool: Boolean or subclass quantity to represent
markup: {True} | False: Whether or not to add backticks around converted text

Outputs:

txt: str: Text representation for reST

Versions:

2019-04-24 @ddalle: Version 1.0

cape.tnakit.rstutils.py2rst_dict(v, **kw)¶

Convert a dict to reST text

Call:

>>> txt = py2rst_dict(v, **kw)

Inputs:

v: dict: Python dictionary to convert to reST text
alignfields: True | {False}: Option to align right-hand side if text fits on one row
sort: True | {False}: Whether or not to sort dictionary keys
sortkey: {None} | function: Function to use for sorting if sort is True
sortreverse: True | {False}: Option to reverse the sort if sort is True
markup: True | {False}: Default value for option to add backticks
indent: {0} | int ≥ 0: Number of spaces of indentation
hang: {indent} | int ≥ 0: Number of spaces of indent for continuation lines
tab: {4} | int ≥ 0: Number of spaces to add to deeper indentation levels
maxcols: {79} | int > 0: Maximum number of columns in a line
markuplength: {50} | int ≥ 0: Cutoff length for default marked strings
fmt: True | False: Format string for int and float entries
markups: dict[bool]: Specific markup for types "int", "float", "None", "str", "__repr__", and "__str__"
fmts: dict[str]: Specific fmt for types "int" and/or "float"

Versions:

2019-04-25 @ddalle: Version 1.0

cape.tnakit.rstutils.py2rst_float(x, markup=False, fmt='%s')¶

Convert a Python float to reST text

Call:

>>> txt = py2rst_float(x, markup=False, fmt="%s")

Inputs:

x: float: Floating-point number to represent
markup: True | {False}: Whether or not to add backticks around converted text
fmt: {"%s"} | str: Format string to convert i (printf style)

Outputs:

txt: str: Text representation for reST

Versions:

2019-04-24 @ddalle: Version 1.0

cape.tnakit.rstutils.py2rst_int(i, markup=False, fmt='%s')¶

Convert a Python int to reST text

Call:

>>> txt = py2rst_int(i, markup=False, fmt="%s")

Inputs:

i: int: Integer to represent
markup: True | {False}: Whether or not to add backticks around converted text
fmt: {"%s"} | str: Format string to convert i (printf style)

Outputs:

txt: str: Text representation for reST

Versions:

2019-04-24 @ddalle: Version 1.0

cape.tnakit.rstutils.py2rst_list(V, **kw)¶

Convert a list to reST text

Call:

>>> txt = py2rst_list(V, **kw)

Inputs:

V: list | tuple: List of Python quantitites to convert
markup: True | {False}: Default value for option to add backticks
indent: {0} | int ≥ 0: Number of spaces of indentation
hang: {indent} | int ≥ 0: Number of spaces of indent for continuation lines
maxcols: {79} | int > 0: Maximum number of columns in a line
markuplength: {50} | int ≥ 0: Cutoff length for default marked strings
fmt: True | False: Format string for int and float entries
markups: dict[bool]: Specific markup for types "int", "float", "None", "str", "__repr__", and "__str__"
fmts: dict[str]: Specific fmt for types "int" and/or "float"
strlist: True | {False}: Option to always use list for lists of strings

Versions:

2019-04-25 @ddalle: Versopm 1.0
2021-03-24 @ddalle: Version 1.1; strlist option

cape.tnakit.rstutils.py2rst_mod(mod, markup=True)¶

Convert a Python module to reST text

Call:

>>> txt = py2rst_mod(mod, markup=True)

Inputs:

mod: module: A Python module
markup: {True} | False: Option to use reST :mod: role

Outputs:

txt: str: Text representation for reST

Versions:

2019-12-27 @ddalle: Version 1.0

cape.tnakit.rstutils.py2rst_none(markup=True)¶

Convert Python None to reST text

Call:

>>> txt = py2rst_none(markup=True)

Inputs:

markup: {True} | False: Whether or not to add backticks around converted text

Outputs:

txt: str: Text representation for reST

Versions:

2019-04-24 @ddalle: Version 1.0

cape.tnakit.rstutils.py2rst_str(s, **kw)¶

Convert a Python str to reST text

Call:

>>> txt = py2rst_str(s, **kw)

Inputs:

s: str: String to convert
indent: {0} | int ≥ 0: Number of spaces of indentation
hang: {indent} | int ≥ 0: Number of spaces of indent for continuation lines
maxcols: {79} | int > 0: Maximum number of columns in a line
markuplength: {50} | int ≥ 0: Cutoff length for default marked strings

Outputs:

txt: str: Marked up reST text

Versions:

2019-04-25 @ddalle: Version 1.0

cape.tnakit.rstutils.rst_directive_option(k, v)¶

Convert an option name and value to an reST directive option

Call:

>>> txt = rst_directive_option(k, v)

Inputs:

k: str: Name of the option
v: any: Value for the option

Outputs:

txt: str | unicode: reST version of the option declaration

Cases:

v	txt
`None`	`""`
`True`	`":%s:" % k`
Else	`":%s: %s" % (k, v)`

Versions:

2019-02-24 @ddalle: Version 1.0

cape.tnakit.rstutils.rst_figure(ffig, caption, **kw)¶

Write the reST command to include an image

Call:

>>> txt = rst_figure(ffig, caption, **kw)

Inputs:

ffig: str: Name of image to include (often like "myimage.*")
caption: str | unicode: Caption to use to describe figure
tab: {" "} | int: Indent character for a tab (default is 4 spaces)
indent: {tab} | str: Indentation to place before each line
width: {None} | str: Image width option value
maxcol, maxcols, cwidth: {79} | int > 0: Column number at which to wrap caption

See Also:

rst_image_lines()

Outputs:

txt: str: Text of directive

Versions:

2019-02-24 @ddalle: Version 1.0

cape.tnakit.rstutils.rst_image(ffig, caption=None, **kw)¶

Write the reST command to include an image

Call:

>>> txt = rst_image(ffig, caption=None, **kw)

Inputs:

ffig: str: Name of image to include (often like "myimage.*")
caption: {None} | str: Caption to use to describe image
indent: {""} | str: Indentation to place before each line
tab: {" "} | int: Indent character for a tab (default is 4 spaces)

See Also:

rst_image_lines()

Outputs:

txt: str: Text of directive

Versions:

2019-02-24 @ddalle: Version 1.0

cape.tnakit.rstutils.rst_image_lines(ffig, directive='image', **kw)¶

Write the reST command to include a figure

Call:

>>> lines = rst_image_lines(ffig, directive="image", **kw)

Inputs:

ffig: str: Name of image to include (often like "myimage.*")
directive: {"image"} | "figure": Which image-inclusion command to use
tab: {" "} | int: Indent character for a tab (default is 4 spaces)
sub, tag: {None} | str: Abbreviated name to use for a substitution instruction
width: {None} | str: Image width option value
name: {None} | str: Reference “name” to be used by later :ref: calls
target: {None} | str: URI for clickable image
alt: {None} | str: Alternate text if image cannot be displayed
figwidth: {None} | str: Width for figure, which contains an image ("figure" only)
maxcol, maxcols, cwidth: {79} | int > 0: Column number at which to wrap

Outputs:

lines: list (str): List of lines of text

Versions:

2019-02-22 @ddalle: Version 1.0

cape.tnakit.rstutils.rst_image_table(imgtable, caption=None, directive='table', **kw)¶

Process lines used to create a reST table of images

Call:

>>> txt = rst_image_table(imgtable, **kw)

Inputs:

imgtable: list (list): List of rows; each row is a list of cell contents
cell11: tuple | str: See unpack_image_cell()
colwidth, cellwidth: {72/ncol} | int > 0: Minimum column width
cell_options: {{}} | dict: Default cell options, passed to rst_image_table_lines()

Outputs:

lines: list (str): List of lines describing the table itself, without indentation
subs: str: Substitution definition text to insert after the table

Versions:

2019-02-26 @ddalle: Version 1.0

cape.tnakit.rstutils.rst_image_table_lines(imgtable, **kw)¶

Process lines used to create a reST table of images

Call:

>>> lines, subs = rst_image_table_lines(imgtable, **kw)

Inputs:

imgtable: list (list): List of rows; each row is a list of cell contents
cell11: tuple | str: See unpack_image_cell()
colwidth, cellwidth: {72/ncol} | int > 0: Minimum column width

Outputs:

lines: list (str): List of lines describing the table itself, without indentation
subs: str: Substitution definition text to insert after the table

Versions:

2019-02-26 @ddalle: Version 1.0

cape.tnakit.rstutils.rst_param_list(keys, types, descrs, alts={}, **kw)¶

Write a docstring for a list of parameters

Call:

>>> txt = rst_param_list(keys, types, descrs, alts={}, **kw)

Inputs:

keys: list[str]: List of parameters to describe
types: dict[str]: Docstring of types for each key in keys
descrs: dict[str]: Docstring of descriptions for each key in keys
alts: {{}} | dict[str]: Dictionary of optional names for certain keys
indent: {4} | int > 0: Indent spaces for each line
tab: {4} | int > 0: Additional spaces for further indentation
width: {72} | int: Maximum width for line of text (including spaces)
strict: {True} | False: If False, skip keys with missing type or description

Outputs:

txt: str: Text in CAPE docstring format describing keys

Versions:

2019-12-19 @ddalle: Version 1.0

cape.tnakit.rstutils.rst_title(title, char='-', margin=2, before=False)¶

Create an ReST title from string

This adds characters before (optionally) and after the title, creating valid syntax for ReStructuredText titles. Examples of valid titles with the input string "Sample Title" are shown below:

Sample Title
--------------

==============
Sample Title
==============

************
Sample Title
************

Call:

>>> txt = rst_title(title, char="-", margin=2, before=False)

Inputs:

title: str | unicode: Input string, must be one line
char: {"-"} | "=" | "*" | "^": Valid reST title adornment character (there are more than 4)
margin: {2} | int >= 0: Extra characters to place after end of character
before: True | {False}: Whether or not to use and adornment line before title

Outputs:

txt: str | unicode: String with title, adornment line(s), and 2 or 3 newline chars

Versions:

2019-02-22 @ddalle: Version 1.0

cape.tnakit.rstutils.unpack_image_cell(cell)¶

Unpack contents of an image table cell

Call:

>>> ffig, cap, kwj = unpack_image_cell(cell)
>>> ffig, cap, kwj = unpack_image_cell(ffig)
>>> ffig, cap, kwj = unpack_image_cell((ffig,))
>>> ffig, cap, kwj = unpack_image_cell((ffig, cap))
>>> ffig, cap, kwj = unpack_image_cell((ffig, kwj))
>>> ffig, cap, kwj = unpack_image_cell((ffig, cap, kwj))

Inputs:

cell: tuple | list | str: Tuple of figure name, caption, and options or just figure name
ffig: str: Name of figure to include
cap: str: Caption to use with cell contents
kwj: dict: Dictionary of specific options for this cell

Outputs:

ffig: str: Name of figure to include
cap: {None} | str: Caption to use with cell contents
kwj: {{}} | dict: Dictionary of specific options for this cell

Versions:

2019-02-25 @ddalle: Version 1.0

`cape.tnakit.rstutils`: Tools for writing ReST files¶

Previous topic

Next topic

This Page

cape.tnakit.rstutils: Tools for writing ReST files¶

`cape.tnakit.rstutils`: Tools for writing ReST files¶