B.1 Overview#
[1t] Summary#
rivt is an open source Python project that imports the rivtlib Python package and dependencies ([6t] Python Requirements). 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 assembled into a rivt report.
rivt files are generally edited and run in an IDE. The lightweight Pyzo IDE is installed with rivtlib. The VSCode IDE is a full featured IDE that is part of the rivt framework and included with [3t] Portable-rivt-vscode.
rivt file examples are provided here. An interface for searching public rivt files on GitHub is here. A public rivt file is are the parts of a rivt file the author chooses to share under an Open Source license. rivt itself is distributed under the MIT open source license. (see [2t] Licenses).
[2t] rivt docs#
rivt Doc Processing
Each rivt file outputs a corresponding doc in the format specified in rv.D() API. A rivt file 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. The prefix is used to organize reports into divisions and subdivisions.
Corresponding rivt docs are output as:
rvAnn-filename.txt
rvAnn-filename.pdf
rvAnn-filename.html
A rivt report is organized using the rivt file numbers. If the rivt file names are:
rvA01-filename.py
rv105-filename.py
rv212-filename.py
the corresponding doc numbers in the would be:
A.1 (division A, subdivision 1)
1.5 (division 1, subdivision 5)
2.12 (division 2, subdivision 12)
Docs are sorted alpha-numerically into divisions and subdivisions. A doc number corresponds to a report subdivision. Note that leading zeroes are dropped in the formatted output.
[2t] rivt API#
The rivt API includes API functions, [3t] Tags and Commands 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.
An API function starts in the first column and takes a triple quoted rivt string (rS) containting rivt markup as the 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] Files/Folders#
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 hyphens rather than spaces to separate words in a file name. They are replaced with spaces when a doc title is extracted.
The top level folder structure is shown below. A more detailed description of the folder structure is here.
[rivt-]Report-Label/ Report Folder
├── conf.py configuration file
├── rv101-filename1.py rivt file
├── rv102-filename2.py rivt file
├── rv201-filename3.py rivt file
├── rv202-filename4.py rivt file
...
├── .vscode/ optional VSCode settings
├── _publish/ published docs and reports
├── _rstdocs/ restructured text files
├── _shared/ public rivt files
├── _stored/ stored files
├── Src/ author source files
└── README.txt searchable text report
[5t] Framework#
The rivt framework includes separate programs that provide additional editing , formatting, version control, and diagramming tools.
Purpose |
Link |
|---|---|
Editing |
|
Editing Extensions |
|
Added Formatting |
|
Version Control |
|
2D Diagramming |
|
3D Diagramming |