4.2 - Documents#

rivt files and source files are typically stored in rivt project folders and subfolders. Reports are assembled from and written to files in the project folder which has the top level structure of:

[rivt]-Project-Label/             Project Folder
    ├── [dv01-]divlabel/          division folder
    ├── [dv02-]divlabel/          division folder

    ...

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

A expanded example of a project folder is here

rivt files are processed one at a time. Sources used in a doc are read from source subfolders. Docs that are part of reports are written to subfolders of the reports folder.

[01] Single Docs

For a simple document that will not be part of a report, a single doc may also be published using only the local folder, without reference to the project folder. In this case all of the source files are read from, and docs are written to, the same folder as the rivt file.

A single doc is published by including the following:

  1. For all commands with a path, including | DOCS | ,the path is specified as rvlocal.

  2. For the Value API function (rv.V) add the rvlocal parameter to any other write parameters. Separate parameters with a comma.

  3. Ensure that any source files for the doc are in the local folder.

Any rivt file can be converted to a single doc using the above steps. The text, PDF and HTML docs will be written to the local file using standard format settings built into rivtlib. The formatting is simpler than report formatting - which may be modified by the author on a per report basis.

[02] Reports

Reports are assembled from docs, which are produced by rivt files - each rivt file produces one doc. A typical workflow for writing reports is to start with a similar report and then edit it file by file to produce a group of docs.

A report is generated by editing and running a script with a number of settings that specify doc assembly and naming overrides. A setting is provided to regenerate all docs before report assembly. The report written to a subfolder of the reports folder.

A typical report generating script is shown below. Note that many aspects of report appearance are already determined at the doc level.

#! 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