B.1 Overview#

[1t] Summary#

rivt is an open source Python project that includes rivtlib and approximately two dozen additional [6t] Project requirements. The lightweight Pyzo IDE is installed for editing and publishing rivt file examples.

A rivt file publishes a formatted rivt doc as a text, PDF or HTML file. A rivt file is a Python file (.py) that imports the rivtlib Python package and includes rivt markup. A collection of rivt docs may be collated as a rivt report.

rivt file examples are provided here and here. An interface for searching rivt files on GitHub is here. All or parts of a rivt file the author chooses to share as a public rivt file can be shared under an Open Source license. rivt itself is distributed under the MIT open source license. (see [2t] Licenses).

The rivt API includes API functions, [2t] Markup and files. The API is designed to be:

  • lightweight

    rivt markup is made up of about 3 dozen tags and commands, and wraps reStructuredText.

  • flexible

    A rivt file produces a text, HTML or PDF doc. Multiple docs can be organized into a report.

  • extensible

    rivtlib is written in Python with direct access to thousands of Python packages.

rivt Doc Processing

rivt flow chart

Each rivt file outputs a corresponding doc in the format specified in rv.D. A doc number has the form:

rvAnn-filename.py

where rv is a required prefix, A is an alphanumeric character and nn are two digit non-negative integers.

A rivt report is organized using the rivt doc numbers. If the rivt file names are:

rvA01-filename.py
rv105-filename.py
rv212-filename.py

the report numbers would be:

  • A.1 (division A, subdivision 1)

  • 1.5 (division 1, subdivision 5)

  • 2.12 (division 2, subdivision 12)

Note that leading zeroes are dropped. Docs are sorted alpha-numerically into divisions and subdivisions in the report.

Docs are assembled from sources and published using a specified folder structure. The singledocB variable overrides the default report structure and specifies that resource files and docs are read from and written to the rivt file folder. It is intended for simpler, standalone docs with more limited format control. The comment variable is specified immediately after the import statement:

import rivtlib.rvapi as rv

# rv singledocB = True

The default setting is False.

here.

[2t] Markup#

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

The header substring specifies the section title and other processing parameters. The content substring includes rivt markup and other arbitrary text. For further details see here.

rv._("""Section Label | parameters

     Content text that is
     indented four spaces.

    ...

    """)

[3t] Folder/Files#

A rivt file is a Python plain text file ( .py ) that includes rivt markup and imports the rivtlib package and API into the rv namespace:

import rivtlib.rvapi as rv

rivt files are stored in a root folder designated with the prefix rivt-. Each rivt file and corresponding rivt doc has a prefix that is used to organize the report. The prefix has the form

rvANN-filename.py

where A is an alpha-numeric character used for organizing report divisions, and NN is a two digit number used to organize sub-divisions. The file name is used as the doc title unless overridden in rv.D. Use underscores or hyphens rather than spaces to seprate words in the file name. They are replaced with spaces when a doc title is extracted.

Folder Key
  1. Required names or prefixes are shown in brackets [ ].
  2. Required folders start with a capital letter.
  3. Folders that contain author provided files are marked with a single vertical bar ( | ).
  4. Folders that contain rivtlib generated files are marked with a double vertical bar

Primary Folders

[rivt]-Report-Label/                Report Folder Name
    ├── [rv101-]filename1.py        | rivt file
    ├── [rv102-]filename2.py        | rivt file
    ├── [rv201-]filename3.py        | rivt file
    ├── [rv202-]filename4.py        | rivt file

    ...

    ├── [Public]/                   || public rivt files
    ├── [Publish]/                  || doc and report files
    ├── [Src]/                      |  source files provided by authors
    ├── [Stored]/                   || stored files written by rivtlib
    └── README.txt                  || searchable text report

The four primary rivt folders are:

Public

Stores public rivt files generated by rvitlib. File content intended for sharing is defined by section headers. Public rivt files are identified by a hyphen after the rv prefix e.g. rv-101-filename1.

Publish

Stores docs and reports generated by rvitlib

Src

Stores images, data, code and text provided by the author.

Stored

Stores files generated by rvitlib. Files include stored sections identified in headers, api log files and processing log files. Files may be attached to a report.

The complete folder structure with subfolders is shown here.