C.2 Files - Folders#
[1] File Types#
rivt file
A rivt file provides the formatting instructions and content that generate rivt docs. Each rivt file has a doc number prefix that specifies the division and subdivision of the doc. rivt reports are assembled using doc numbers. The doc number prefix includes a single digit capital alphanumeric division label D, followed by a two digit subdivision number ss. For example:
[rvDss-]file-name.py
rvB02-Beam-Loads.py
Author provided source file inputs
rivt reads and writes a variety of files including:
description |
read file types |
|---|---|
Image files |
.png, .jpg, .jpeg |
Data files |
.csv, xlsx, |
Pandas dataframes |
.dat, html, hdf5, .json, xml, feather, parquet |
Formatted text files |
.txt, .tex, html, .md, .rst |
Shell and terminal commands |
.sh, .bat, .cmd |
Files for use in a rivt doc are stored in the rvsrc folder and any author created subfolders. File paths are give relative to the rivt-report folder. Files are read using rivt commands. For example, to read and insert an image file in the author created subfolder img the command would be:
IMAGE | rvscr/img/filename.png | parameters
Available commands and tags depend on the API function, summarized here
Source files generated by rivtlib
rivt also generates files that can be read by subsequent rivt files. These generated files are written to the rv_stor folder and subfolders and include:
description |
written file types |
|---|---|
Value files |
.csv |
Stored sections |
.txt |
Log files |
.txt |
Python output |
.png, .jpg, .csv, .dat, xlsx |
Formatted text files |
.txt, .tex, html, .md, .rst |
Public rivt files |
.py |
Value files
A value file is a csv file that defines variable values. A file with all values is written to rv_stor for each Values API call. The filename has the form:
vDss-S-rivtfile.csv
where Dss is the doc number, S is the section number, and rivtfile.csv is the original rivt file name. The file may be read using the VALUE command.
Log files
Log files include a backup of each rivt file and a record of most steps of rivt file processing and are written to the /logs subfolder of rv_stor. They are written when the PUBLISH command is executed. Each log file has the form:
log-Dss-rivtfile.txt
Python scripts
Python scripts can be run as a [[PYTHON]] block in the Run API or as an imported file in the Values API. The [[PYTHON]] block is written to rv_stor with label name. For consistentcy, Python output should also be directed to rv_stor.
Public rivt files
A public rivt file is a copy of the rivt file that includes all of the sections marked as public in the header. It has the same name as the rivt file with an added hyphen between “rv” and the docnumber e.g.
rv-Dss-filename.py
[2] Folder Names#
Reports are organized using the folllowing folders and subfolders.
- rivt- report-label
Top level rivt folder containing rivt report and public files.
- _rivt-public
Includes public rivt files designated byt the author written by rivtlib for public sharing. The prefix rvAnn- is changed to rv-Ann- to avoid confusion with non-public files.
- rivt-report
Includes files and folders for publishing docs and reports.
required subfolders of rivt-report
- rvsrc
Includes author provided source files used by rivt files including data, images, run commands, tools and value files.
- rv_stor
Includes output files written by rivtlib including logs, values, hidden sections and metadata that may be read by other rivt files.
- _published
Formatted docs and reports written by rivtlib for publication. Subfolders include docs (HTML), pdfdocs (PDF) and txtdocs (text).
- _rstdocs
Intermediate restructured text files written by rivtlib.
[3] Folder Structure#
Folder Naming
A rivt folder can contain any file or folder but the following structure is required for doc processing. rivt folders include at least the folders and files shown in brackets[] below. Folders with an underscore prefix contain rivt generated files. Files and folders are organized under a rivt root folder with the prefix rivt- followed by the report label, e.g. rivt-Report-Label.
A new rivt folder is typically started by copying and editing a similar folder. Several rivt-folders can be downloaded at openmodels.info.
A typical rivt folder structure is shown below. The required rivt file names and prefixes are shown in brackets.
Top Level Folders
[rivt-]Report-Label/ rivt Folder
├── .vscode/ optional VSCode settings
├── README.txt rivt-generated report
├── [_rivt-public]/ public subset of rivt files
├── rv_stor/
├── rvsrc/
├── README.txt
├── rv-101-filename1.py
├── rv-102-filename2.py
├── rv-201-filename3.py
...
└── [rivt-report]/ report folder
├── [_published]/ published docs and reports
├── [_rstdocs]/ restructured text files
├── [rv_stor]/ rivt generated source files
├── [rvsrc]/ author provided source files
├── [rv101-]filename1.py rivt file
├── [rv102-]filename2.py rivt file
├── [rv201-]filename3.py rivt file
...
Expanded Folders
[rivt-]Report-Label/ rivt Folder
├── .vscode/ optional VSCode settings
├── README.txt rivt-generated text report
├── [_rivt-public]/ rivt-generated public files
├── rvsrc/ author source files
├── rv-101-filename1.py public rivt file
├── rv-102-filename2.py public rivt file
├── rv-201-filename3.py public rivt file
...
├── [rivt-report]/ report folder
├── [rivt-report]-1.py report generating script
├── [rv101-]filename1.py rivt file
├── [rv102-]filename2.py rivt file
├── [rv201-]filename3.py rivt file
...
├── [rvsrc]/ author provided files and folders
├── [downloads]/ files to download
└── conc-vals.txt
├── [page]/ page layout images
├── favicon.png
├── covlogo1.png
└── runlogo1.png
├── data/ tables
└── steel-vals.csv
├── tools/ OS shell commands
└── opensees.sh
├── fig1.png
└── fig2.jpg
├── [rv_stor]/ rivt-generated source files
├── [logs]/ log files
├── rv101-log.txt
└── rv102-log.txt
├── [sect]/ sections not printed
├── rv202-5d.txt
├── rv103-4t.txt
└── rv301-2r.txt
├── [temp]/ temp files
└── rv101-label3.tex
├── output.dat
├── v101-2.csv
└── v102-3.csv
├── [_published]/ rivt-published docs and reports
├── [docs]/ html docs
├── html auxiliary folders
├── index.html
├── rv101-filename1.html
├── rv102-filename2.html
├── rv201-filename3.html
...
├── [pdfdocs]/ pdf docs
├── pdf auxiliary folders
├── report-title.pdf
├── rv101-filename1.pdf
├── rv102-filename1.pdf
├── rv201-filename3.pdf
...
└── [txtdocs]/ text docs
├── report-title.txt
├── rv101-filename1.txt
├── rv102-filename1.txt
├── rv201-filename3.txt
...
└── [_rstdocs]/ rivt-generated rst files
├── _downloads/
├── _static/
├── rv101-filename1.rst
├── rv102-filename2.rst
├── rv201-filename3.rst
...