C.1 Markup#
[1t] API functions#
rivt has seven API functions. The name rivt is an acronym taken from the four functions that process content.
Content APIs- [R]un executes shell commands.
- [I]nsert adds static table, image, equation and text content.
- [V]alues evaluates equations and functions.
- [T]ools runs reStructuredText, HTML, LaTeX and Python scripts.
- Doc specifies the doc type and style.
- Skip can be used for interactive debugging and comments.
- Exit can be used for interactive debugging.
API Function |
Name |
Purpose |
|---|---|---|
rv.R (rS) |
Run |
Run shell commands |
rv.I (rS) |
Insert |
Insert static sources |
rv.V (rS) |
Values |
Calculate values |
rv.T (rS) |
Tools |
Python and markup scripts |
rv.D (rS) |
Doc |
Publish docs |
rv.S (rS) |
Skip |
Skip section (comments and debugging) |
rv.X (rS) |
Exit |
Exit rivt (debugging) |
If interactive IDEs like VSCode or Spyder are used to edit and run rivt files, each API function can be processed as a cell (similar to Jupyter Notebooks) by using the standard prefix notation:
# %% optional label
rv.API_FUNCTION("""rivt string""")
[2t] rivt string#
Each API function takes a triple quoted rivt string argument composed of two parts - a header substring followed by a content substring.
The first line of the rivt string is a header substring that defines section processing. It is followed by a content substring that includes rivt markup. The content substring is indented four spaces for improved readability and section folding.
Header substring
The header substring starts with a section label followed by vertical bar that deliniates three comma separated section parameters that can override default behavior. The section label is the section title.
rv._("""Section Label | doc;stored, private;public, section;merge
Content substring indented 4 spaces
...
""")
The parameters include the following, in any order:
- private/public
Determines whether the API section text is copied to the the /public folder rivt file for sharing.
- doc/stored
Determines whether the rivt string is formatted and printed in the doc, or just annotated in the doc and written to a file in the Stored folder for optional inclusion as an appendix.
- section/merge
Determines whether the API starts a new doc section or is merged into the previous section.
Default settings in the header substring do not need to be specified. The default setting for each API is listed first (in bold) in the table below.
API |
private;public |
doc;stored |
section;merge |
|---|---|---|---|
rv.R |
private;public |
stored;doc |
merge;section |
rv.I |
private;public |
doc;stored |
section;merge |
rv.V |
private;public |
doc;stored |
section;merge |
rv.T |
private;public |
stored;doc |
merge;section |
rv.S |
private;public |
stored |
merge |
rv.D |
public |
stored |
merge |
rv.X |
Examples of header substring settings are shown below.
An example with explicit defaults (they do not have to be declared).
# This
rv.I("""A New Section | private, doc, section
Content text
...
""")
# is equivalent to:
rv.I("""A New Section
Content text
...
""")
An example that merges a section into the previous section.
rv.I("""A Merged Section | merge
Content text
...
""")
Content substring
The content substring is indented four spaces for legibility and code folding. It includes line tags, block tags and commands along with text.
rv._("""Section Label
Content text indented 4 spaces.
...
""")
Content is converted line by line into formatted text and RestructuredText, and then further processed into HTML or PDF. If a line does not contain a command or tag it is passed through as is, which allows for the Insert function (rv.I) including some restructured text directly i.e. surrounding words with * or ** will format a word as italic or bold respectively.
In addition block tags in the Tools function (rv.T) directly supports processing HTML, LaTeX and reStructuredText scripts.
[4t] Folders#
Folders provide standard file locations that simplify doc and report generation.
Folder Key
- Required names or prefixes are shown in brackets [ ].
- Folders (including subfolders) that contain author generated files
are marked with a single vertical bar ( | ).
- Folders (including subfolders) that contain *rivtlib* generated files are
marked with double vertical bars ( || ).
Folders
[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
...
├── [public]/ || public rivt files
├── [publish]/ || doc and report files
├── [src]/ | source files from author
├── [stored]/ || rivt stored files
└── README.txt || searchable text report
Expanded Folders
[rivt]-Report-Label/ Report Folder Name
├── [rv101-]filename1.py | rivt input files
├── [rv102-]filename2.py
├── [rv201-]filename3.py
├── [rv202-]filename4.py
├── [public]/ || public rivt files
├── rv-101-filename1.py
├── rv-201-filename3.py
└── rv-202-filename4.py
├── [publish]/ || reports and docs
├── [html]/ HTML site
├── [docs]/
├── _images/
├── _sources/
├── _static/
├── rv101-filename1.html
├── rv102-filename2.html
├── rv201-filename3.html
├── rv201-filename4.html
└── index.html HTML site entry point
├── rv101-filename1.rst intermediate rst files
├── rv102-filename2.rst
├── rv201-filename3.rst
└── rv202-filename4.rst
├── [pdf]/ PDF from rst2pdf
├── [src]/ intermediate rst files
├── rv101-filename1.rst
├── rv102-filename2.rst
├── rv201-filename3.rst
└── rv202-filename4.rst
├── rv101-filename1.pdf PDF docs from rst2pdf
├── rv102-filename2.pdf
├── rv201-filename3.pdf
├── rv202-filename4.pdf
└── Report-Label.pdf PDF report from rst2pdf
├── [pdftex]/ PDF from LaTeX
├── [src]/ intermediate rst files
├── rv101-filename1.rst
├── rv102-filename2.rst
├── rv201-filename3.rst
└── rv202-filename4.rst
├── rv101-filename1.pdf PDF docs from LaTeX
├── rv102-filename2.pdf
├── rv201-filename3.pdf
├── rv202-filename4.pdf
└── Report-Label.pdf PDF report from LaTeX
├── [text]/ text report
├── rv101-filename1.txt text docs
├── rv102-filename2.txt
├── rv201-filename3.txt
├── rv202-filename4.txt
└── README.txt searchable text report
├── [src] | source files from author
├── data/ author created subfolder
├── data1.csv
└── conc-vals.csv
├── image/ author created subfolder
├── fig1.png
└── fig2.jpg
├── output/ author created subfolder
├── table1.csv
├── image1.png
└── opensees1.txt
├── [gendoc]/
├── gen-html.cmd html generating script
├── gen-pdf.cmd pdf generating script
├── gen-pdftex.cmd LaTeX generating script
├── rivt-report.py report generating script
├── new-units.py define new units
└── [style]/ doc style files
├── [html]/ html style files
├── _locale/
├── _static/
├── _templates/
├── conf.py
├── genhtml.cmd
└── index.rst
├── [pdf]/ rst2pdf style files
├── fonts/
├── style/
├── Report-Cover.pdf
└── genrst2pdf.cmd
├── [pdftex]/ pdftex style files
├── gentexpdf.cmd
├── Report-cover.pdf
└── rivt.sty
├── [text]/ text ini file
└── rv-text.ini
├── [py]/ Python scripts and functions
├── plot.py
└── loads.py
└── [vals]/ value files
├── steel-vals.csv
└── plastic-vals.csv
├── [stored]/ || stored files from rivt
├── [logs]/ log files
├── rv101-api.txt
├── rv101-log.txt
└── rv102-log.txt
├── [sect]/ stored sections
├── rv202-5d.txt
├── rv103-4t.txt
└── rv301-2r.txt
├── [temp]/ temp files
└── rv101-label3.tex
└── [vals]/ stored value files
├── v101-2.csv
└── v102-3.csv
└── README.txt || searchable text report