D.1 Markup#

[1] API functions#

rivt has six API functions. The name rivt is an acronym taken from the four functions that process content. The remaining three functions are used for document generation and debugging.

Content APIs
  1. [R]un Runs Python scripts and markup.
  2. [I]nsert Adds static tables, images and equations.
  3. [V]alues Evaluates equations and functions.
  4. [T]ools Executes shell scripts and external programs.

Publish APIs
  1. [D]oc specifies the doc type and style.
  2. [S]kip, e[X]it can be used for interactive debugging and comments.

API Function

Name

Purpose

rv.R (rS)

Run

Run scripts and markup

rv.I (rS)

Insert

Insert static sources

rv.V (rS)

Values

Calculate values

rv.T (rS)

Tools

Shell scripts and external programs

rv.D (rS)

Doc

Publish docs

rv.S,X (rS)

Skip, Exit

Skip section, exit (comments and debugging)

API functions define doc sections. The available rivt markup commands and tags depends on the API funciton. If interactive IDEs are used, API functions can be processed individually using the standard notebook cell percent notation:

# %% optional label
rv.API("""rivt string""")

[2] rivt string#

Each API function takes a triple quoted rivt string argument composed of a header substring line followed by a multiple-line content substring. The header substring defines section processing parameters. The content substring includes rivt markup and is indented four spaces for improved readability and navigation (e.g. section folding).

Header substring

The header substring starts with a section label, used as the section title, followed by a vertical bar and three comma separated section parameters that override default behavior.

rv._("""Section Label | doc;stored, private;public, section;merge

     Content substring indented 4 spaces

    ...

    """)

The header parameters include the following comma separated values in any order:

private/public

Determines whether the API section text is copied to the the Public folder rivt file for sharing.

doc/stored

Determines whether the rivt string is formatted and printed in the doc, or just annotated in the doc and written to a file in the Stored folder for optional inclusion as an appendix.

section/merge

Determines whether the API starts a new doc section or is merged into the previous section.

Default settings in the header substring do not need to be specified. The default setting for each API is listed first (in bold) in the table below. The default privacy settings for all sections in a rivt file may be reversed by including the public comment setting immeditely following the rivlib import statement.

import rivtlib.rvapi as rv

# rv setpublic = true

Individual sections may still be set as private in the header substring.

API

private; public

doc; stored

section; merge

rv.R

private; public

stored; doc

merge; section

rv.I

private; public

doc; stored

section; merge

rv.V

private; public

doc; stored

section; merge

rv.T

private; public

stored; doc

merge; section

rv.S

private; public

stored

merge

rv.D

public

stored

merge

rv.X

Examples of header substring settings are shown below.

  • An example with explicit defaults (they do not have to be declared).

# This

rv.I("""A New Section | private, doc, section

    Content text
    ...

    """)

# is equivalent to:

rv.I("""A New Section

    Content text

    ...

    """)

  • An example that merges a section into the previous section.

rv.I("""A Merged Section | merge

    Content text

    ...

    """)

Content substring

The content substring is indented four spaces for legibility and code folding. It includes line tags, block tags and commands along with text.

rv._("""Section Label

    Content text indented 4 spaces.
    ...

    """)

Content is converted line by line into formatted text and RestructuredText, and then further processed into HTML or PDF. If a line does not contain a command or tag it is passed through as is, which allows for the Insert function (rv.I) including some restructured text directly i.e. surrounding words with * or ** will format a word as italic or bold respectively.

In addition block tags in the Tools function (rv.T) directly supports processing HTML, LaTeX and reStructuredText scripts.

[3] Tags and Commands#

Line Tags

A line tag formats a line of text and is denoted with a single _[LETTER], placed at or near the end of the line, depending on the tag.

Block Tags

A block tag formats a block of text and begins with _[[TAGNAME]] and terminates with _[[END]].

Commands

rivt commands read and write external files. They typically start in the first column with a vertical bar ( | ) followed by the command name, file path, and parameters.

The exceptions are the definition (==:), assignment (<=:), function (:=:) and compare (<>) commands that are used to define, assign and compare values.

| COMMAND | relative path | parameters

File paths are specified relative to the rivt root folder. The rivt report folder structure is described here.

If the path is ommitted the default path for each command is applied. If the singledoc parameter is set, the resource files and docs are stored in the rivt root folder.

Tag and Command syntax for each API type is defined and described using the following format:

Markup Key

_[TAG] or | COMMAND |

Description

    Syntax:
        _[TAG] or | COMMAND | syntax

    Example:
        This is a sentence. _[C]

[4] Folders#

<p style=”border-width:2px; border-style:solid; border-color:#49b2c3;padding: 1em;”>

<b>Folder Names</b><br> <br>

A rivt folder can contain any set of files and folders but the following structure is required for <i>doc</i> processing. Files and folders are organized under a root folder with the prefix <i>rivt-</i> e.g. <i>rivt-Report-Label</i>. <br> <br>

<i>rivt folders</i> (root folders) include at least the <i>rivt files</i> and the five required subfolders. Required folders and prefixes are shown in brackets. Folders preceded by an underscore contain rivt outputs. Folders requiring author input are capitalized. <br> <br>

The top level folder structure is shown below. A more detailed description of the folder structure is here.

Top Level Folders



rivt-Report-Label/           Report Folder
  ├── .vscode/                  optional VSCode settings
  ├── rivt-public_/             rivt-generated public files
      ├── rvsrc/                     source files
      ├── README.txt                public text report or doc
      ├── rv-101-filename1.py       public rivt file
      ├── rv-102-filename2.py       public rivt file
      ├── rv-201-filename3.py       public rivt file
      ...
  └── rivt-report/               rivt files and docs
      ├── _published/               published docs and reports
      ├── _rstdocs/                 intermediate restructured text files
      ├── rv_stor/                  rivt generated stored files
      ├── rvsrc/                    author source files
      ├── rivt-report.py            report generating script
      ├── rv101-filename1.py        rivt file
      ├── rv102-filename2.py        rivt file
      ├── rv201-filename3.py        rivt file
      ...
  └── README.txt                 text report or doc