D.3 Reports#

<i>

[1] Files and Docs#

The assembly and organization of a rivt report is inferred from:

  1. The rivt file and doc name

  2. The project folder names

A rivt file name has a doc number prefix:

[rvDss-]file-name.py

where ss is a two digit subdivision number. e.g., rvC03-loads.py is subdivision 3 within division C. Each rivt file outputs a doc file with the same doc number prefix. The doc number and project folder structure are used to assemble and organize reports.

Sources used in a doc are read from the source folder.

The division label is taken from division folder label and the division name is taken from the first rivt file name in the division.

Calculated values and generated files can be passed between files. Report rivt files are processed sequentially.

<i>

[2] Project Folders#

rivt project folders organize files that generate docs and reports. The files include rivt files, external source documents, settings, and public/private files. The top level structure is shown below. The full structure is shown here

[rivt]-Project-Label/             Project Folder
    ├──
    ├──

    ...
    ├── [log]/                    source files
    ├── [public]/                 public rivt files
    ├── [report]/                 reports and docs
    ├── [source]/                 source files
    ├── [style]/                  source files
    └── README.txt                text report

A rivt file may also generate a single doc that reads from and writes to the local rivt file folder, independent of the project folders.

<i>

[3] Reports#

A report is assembled from docs. Each rivt file compiles to a doc organized by division and subdivision specified by .

A typical workflow for writing reports is to start with a similar report and then edit the rivt files to produce new docs.

A report is generated by running a Python report script with settings that specify assembly parameters and override defaults. One setting 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. The report generating file must
located in rivtdocs/reports/. The report output file is written to the same
folder. Duplicate report file names are incremented, not overwritten.

Run this Python file to generate a rivt report. Copy and rename the file to
save custom report settings. See rivtdocs/styles/rivt.ini for additional
settings.

A flag determines whether the report is assembled from existing doc files or
whether docs are regenerated prior to assembly. (see "report type and paths"
below). 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 organizes rivt folders into divisions, and rivt doc files as
subdivisions. rivt doc numbers define this structure. Default titles for
subdivisions and divisions are generated by stripping the doc or div number
from the file or folder name and replacing underscores with spaces. The default
titles may be overridden (see "optional rename" below). """

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

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

# ==================================
# include docs / rename titles
# ==================================
# include these divisions in report
dv01 = "Codes and Loads"  # override division title
dv02 = ""  # use default division title from folder name
dv03 = "Foundation"

# include these docs in report
rv0101 = "Codes"  # override doc (subdivision) title in report
rv0102 = ""  # use default subdivision title from file name
rv0201 = "Steel Frame"
rv0202 = "Solar Panels"
rv0301 = "Slab"
rv0302 = "Walls"

genreport()  # noqa: F405