B.1 | R-I-V-T

[1] Summary

rivt uses a wide variety of source materials when publishing docs. They include external programs, images, functions, equations, data files and Python scripts. To assemble a doc it uses four primary API functions:

R(): Processes internal scripts and block text, e.g. Python, LaTeX, rst
I(): Inserts static sources e.g. images, text, and PDF files
V(): Imports data and calculates values from equations and functions
T(): Runs external binary programs

A fourth API for publishing the doc is documented here:

D(): Publishes documents

Examples of a rivt file with text, PDF and HTML docs are here:

• rivt file

• text doc,

• PDF doc

• HTML doc

---

[2] API

The API is designed to be:

• lightweight

  rivt markup wraps reStructuredText and uses fewer than three dozen tags and commands. rivt tags format lines and blocks of text and commands read and write files.

• extensible

  rivtlib is written in Python with direct access to the large library of Python packages and functions. Python scripts and external programs can be integrated into a rivt doc throught the Run and Tools APIs.

• versatile

  A rivt file produces a text, HTML or PDF doc from the same file. Multiple docs can be organized into reports. rivtbooks provide a convenient way to organize files around a subject matter for insertion into reports. rivt can be run within a variety of IDEs.

• efficient

  The file and folder organization is intuitive and it produces clear, organized documents with default settings. Settings may be customized via conf.py and yaml files. A rivt doc can be generated with a single file or, using the same folder structure extendec to a large report involving hundreds of files.

The API methods are listed in the table below, where (rS) is a triple quoted rivt string argument.

API Function	Name	Purpose
rv.R (rS)	Run	Run Python scripts and markup
rv.I (rS)	Insert	Insert static sources
rv.V (rS)	Values	Calculate values
rv.T (rS)	Tools	Execute shell scripts and programs
rv.D (rS)	Doc	Publish docs
rv.S; X (rS)	Skip; Exit	Editing - Skip section or exit program

An API function starts in the first column and takes a triple quoted rivt string argument containing a header and content substring. The first line of the rivt string is the header substring, followed by a content substring indented 4 spaces for readability and section folding. See here for rivt string details.

The rivt API also provides scope for rivt markup

---

[3] File Settings

There are several comment settings that apply to the entire rivt file. These are specified in the comment settings immediately following the import statement. Default settings shown in parentheses do not need to be specified - only variants.

import rivtlib.rvapi as rv

# rv private = false ; default section parameter changed to public (true)
# rv no_tag = true ; API type is added to section number (true)
# rv set_width = 90; character width of text output (80)

# %% My Section Label
rv._("""My Section Label

        Content text and rivt markup - indented four spaces.
    ...

    """)

---

[4] String Header

Individual API methods define sections. Each API function takes a raw, triple quoted rivt string composed of a header substring on the first line followed by a multi-line content substring. The header line defines section processing parameters. The content substring includes rivt markup and is indented four spaces for improved readability and navigation (e.g. section folding). rivt markup commands and tags will vary depending on the API function.

The header substring starts with a section label, also used as the section title, followed by section parameters that override default behavior. All parameters are optional and may be omitted if defaults are acceptable. If any parameters are specified the vertical bars bracketing the file name are required.

The header substring specifies the section title and other processing parameters. The first set of parameters modify section processing. The second parameter provides the option for a template file or script that is processed in addition to the content substring if provided.

The API method header has two general forms: Default and Modified. The default form is used when the header substring accepts default parameters. It only requires a section label. The modified form is used when default parameters need to be modified.

Section Headers

rv._("""Section Label

    Default header for Insert and Values sections.
    Content text and rivt markup, indented four spaces.

    """)

rv._("""Section Label | shmpn

    Header with modifications for Insert and Values sections.
    Content text and rivt markup, indented four spaces.

    """)

rv.D Header

rv.D("""Section Label

    Content text and rivt markup - indented four spaces.

    """)

The first parameter list in the header substring specifies handling of the content substring. The second and third parameters, where applicable, specify a type and file that is processed by the API method before processing any content.

Parameters

Section parameters may be specified in any order or ommitted if defaults are acceptable.

• s | store - stores the section content in _rvstored/sect as a .rvt file.

• h | hide - processes the section but suppresses the doc output.

• m | merge - merges the section with the previous section.

• p | public - toggles the default public/private status of the section (see comments)

• n | new page - Starts a new pdf page.

The default parameters, when ommitted, are as follows:

• section is not stored

• section content is published

• section not merged

• private section

• continuous pages

---

[5] String Content

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, tag or assignment it is passed through as is. This allows the Insert function (rv.I) to include some restructured text directly i.e. surrounding words with * or ** will format a word as italic or bold.

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

[6] Tips

Where interactive IDEs are used rv.S and rv.X can be used for debugging. Cell notation can be used for the navigation panels generated rivtStudio. Note that Ctrl+Alt+C inserts a cell label (# %%) followed by the section title if the cursor is on the first line of the section.