D.2 Files#

<i>

[1] File Types#

rivt file

rivt files are written by the author. Each rivt file has a prefix that specifies the division label and subdivision number of the published doc. rivt reports are assembled using doc numbers that organize the report into divisions and subdivisions. The d*subdivision* name is taken from the name that follows the doc number. It may be overridden in the API Meta function. Division names are specified in the report script.

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

rvC02-Beam-Loads.py

where the default doc name is “Beam Loads” in subdivision 2 of division C. Hyphens are stripped from file name.

Run file

A run file is a shell or command script executed using the | RUN | command.

origin: author input

folder: src/ - or a user created subfolder of /src

API function: rv.R

Insert file

An insert file is an image, table or text file executed using the | IMAGE | , | TABLE | , or | TEXT | command.

origin: author input

folder: src/ - or a user created subfolder of /src

API function: rv.I

Value file

A value file is a csv file that defines variable values. It is imported using the | VALUE | command. Values defined by equations and a _[[VALUES]] block are written to a file with the name composed of the doc and section number. The file may be read by other rivt files.

Read

origin: author input

folder: src/Values - or a user created subfolder of /src

API function: rv.V

Write

origin: program output

folder: src/Values

API function: rv.V

Tool file

Tool files can be executed by | PYTHON | , | HTML | , | RST | or | LATEX | commands. They may be used for analysis and generation of text, tables, images and other formatted content. Executing a tool file may:

  • define functions and classes for use in the rivt file

  • generate images, tables and text for inclusion in the doc

  • insert markup text into the doc

    Read

    origin: author input

    folder: src/Tools or a user created subfolder of /src

    API function: rv.T

    Write

    origin: program output

    folder: src/Tools

    API function: rv.T

Doc file

Each rivt file outputs a doc file with the same doc name and number and the selected doc type suffix. Doc files are written to the publish folder as text, PDF or HTML files using | PUBLISH | command.

PDF files may be prepended or appended to the doc using the | APPEND | command.

origin: program output

folder: src/ - or a user created subfolder of /src

API function: rv.D

Report file

A report file is generated by the Python report script and is written to the designated publish subfolder. The report file name is taken from the report folder name unless specified in the report script.

origin: program output

folder: /publish/ subfolder

Report script

The report script is a Python file that assembles the report. It specifies the docs that should be included, whether the rivt files should be re-executed and other format settings.

origin: author input

folder: /publish

Public rivt file

origin: program output

folder: /public

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

Log file

Log files are written to the log folder. They include:

  • a backup of the rivt file

  • a file listing the execution steps when processing the rivt file

  • a file listing each API function call with the header.

    origin: program output

    folder: /logs

<i>

[2] Folders#

The rivt report folder organizes logs, public rivt files, sources, docs and reports. Top level folders are shown below.

Folder Key

  • Required folder and file prefix names are shown in brackets [ ].

  • Single vertical bar ( | ) identifies files provided by the report author.

  • Double vertical bar ( || ) identifies files written by rivtlib

  • Four vertical bars ( |||| ) are a mix of author and rivtlib written files

[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
    ├── [logs]/                     || log folder
    ├── [public]/                   || public rivt folder
    ├── [publish]/                  || reports folder
    ├── [src]/                      |||| source folder
    └── README.txt                  || Searchable text report

The full report folder structure is here.

<i>

[3] Reports#

A report is assembled from mutliple docs organized by division and subdivsion. Each doc is a subdivion of a report. A typical workflow for writing reports is to start with a similar report and edit the rivt files and report script that produces the report

The Python report script includes settings that specify assembly parameters and override defaults. These include:

  • Docs to be included in the report

  • Division names

  • recompiling docs

  • report cover page and title

provides the option to either regenerate all docs or to assemble the report from previously generated docs. Most aspects of the report appearance are determined at when generating docs.

An example script is shown below.

#! python

from rivtlib.rvreport import *  # noqa: F403

""" generate a rivt report

Sample report generating and config file.

Run this Python file to generate a rivt report. The report generating file
must located in /publish/subfolder where subfolder is the doc type. The
report output file name is the report title. It is written to the same
folder as the report script. Duplicate report file names are incremented.

A flag determines whether the report is assembled from existing doc files
or whether docs are regenerated prior to assembly. If a rivt or doc file is
specified for inclusion and not found a warning is given but the report is
still assembled.

A rivt report is a compilation of rivt docs organized into divisions and
subdivisions. rivt doc numbers define the organization. Default titles for
subdivisions are generated by stripping the doc number from the file name
and replacing hyphens with spaces. The default titles may be overridden in
rv.M for each rivt file.

See src/styles/rivt.ini for additional settings

"""
# ==================================
# report type
# ==================================
rptype = "pdf"  # report type [html; pdf; pdftex; text]
rvrun = False  # regenerate docs [True; False]

# ==================================
# report cover settings
# ==================================
# cover pages are located in /src
rptitle = "Solar Canopy Calculations"
rpsubtitle = "Larkspur, Ca"
rpauthor = "rhh"
rpdate = "<datetime>"
rptoc = True  # add table of contents, "" to omit
rpcover = "/publish/cover1.pdf"  # cover page, "" to omit

# ==================================
# include docs
# ==================================
# include these divisions in report
divlist = [[dv01, "Codes and Loads"],
           [dv02, "Frame"],
           [dv03, "Foundation"]]
# include these docs in report
# doc label is for reference only, may be empty string
doclist = [[rv101,"Codes"],
           [rv102,"Loads"],
           [rv201,"Frame"],
           [rv202,"Solar"],
           [rv301,"Foundation"],
           [rv302,"Walls"]]

genreport()  # noqa: F405