rivt is an open-source program for writing and assembling calculation documents with a focus on reuse [1]. The extensive and ever expanding collection of engineering and scientific software often require that outputs be organized into systematic project documents. rivt markup is used to write live, linked and editable rivt files that organize text, calculations, images, code and output from different sources. rivt compiles and publishes a rivt file as a text, PDF or HTML doc.
The primary purpose of rivt is to provide a stable file and folder format that can be shared, edited, and maintained as a live calculation document to produce formatted reports. rivt files can be organized in rivt folders in two ways:
| A rivt file is the basic input file that
rivt file | compiles to a text, PDF or HTML document (doc).
| It is a Python file (.py) that imports the
| rivtlib Python package and uses rivt markup.
| A rivtbook is a collection of rivt files with
rivtbook folder | common subject matter and a folder structure
| that makes it easy to select files and resources
| for inclusion in docs.
| A rivt report is the collated output of one or more
| rivt docs into a single text or PDF file, or an HTML
rivt report folder | site. A rivt doc is the published output of a rivt
| file. A Python script links and organizes multiple
| docs into a report using rivt file numbers.
For an overview of rivt see here. To get started with running examples see install. For rivt with AI see here. Examples of a rivt file with its text, PDF, and HTML docs are provided in this tutorial.
rivtlib is the Python package that formats and compiles a rivt file to a doc in a second or two. Python knowledge is not required to use rivt but incorporating Python scientific and engineering libraries into a rivt file increases its capabilities. A rivt file may be interactively executed from the top down in an IDE, or from the command line. Multiple rivt files may be compiled into a rivt report. This website is an example of an HTML report. rivt files may also be collected into a rivtbook organized around a common subject matter. rivtbooks are organized for efficient file selection and inclusion in reports.
rivt files and reports may be shared and distributed through any cloud storage service. Examples are available on Google Drive at openmodels.info. If collaboration and version control are needed GitHub may be used. rivt files and reports are organized in top level folders ( rivt project or rivtbook ) which work well as GitHub repositories. rivt also generates a GitHub README file from a rivt report. A convenient interface for searching public rivt READMEs is here..
rivt produces organized, formatted engineering documents from active calculation files using reasonable defaults. Use cases are listed here. A brief discussion of current engineering document tools and their strengths and weaknesses relative to rivt objectives is here. For documents with rigid format requirements, including journal articles and books that do not need active recalculation, Quarto is likely a better fit. For interactive calculation documents that do not need an organized published report, Jupyter Notebooks is likely a better tool.
ver: 1.0.0a18 (Note: rivt is currently alpha sofware. Some features are incomplete and program structure, markup and assignment tags, and commands may change.)