Edit ==== A **rivt** file is a Python file (utf-8 ) with the import statement *import rivtlib.rivtapi as rv* which provides four primary API functions and formatting commands and tags. The API functions take a triple quoted string as the argument. When running in an IDE (e.g. VSCode) the file may be executed interactively. Interactive output is formatted as utf-8 text for speed and compatiblility. API functions may be grouped and executed step-wise using the standard cell decorator *# %%*. Document and report files are generated by the functions *rv.write_public()* and *rv.write_private()* which output files in GitHub Flavored Markdown (GFM) and PDF. {list-table} :header-rows: 1 * - API - name - purpose * - **rv.R(str)** - rivtinit - repository and report settings * - **rv.I(str)** - insert - static text, images and tables * - **rv.V(str)** - rivtinit - values * - **rv.T(str)** - tools - Python functions and scripts Each API function defines a document section. The first line of each function includes a section label that becomes a section title, followed by formatting parameters. New sections may be suppressed by prepending a double hyphen to the label. The section body can contain any utf-8 text. Commands and tags applicable to each function are defined [here](#commands) and [here](#tags). The API function names start in column one. All other content is indented 4 spaces to facilitate section folding, bookmarking and legibility. API functions can be written in any order and frequency except for *rivtinit*, which occurs only once as the initial function in the file. A **rivt** file is a Python file that follows pep8 and ruff conventions. **rivt** markup uses a syntax of commands for file operations and tags for text formatting. Any text not defined with commands or tags is passed through as output. Commands and tags are processed in part by the *docutils* library and [restructuredText](https://docutils.sourceforge.io/docs/user/rst/quickref.html). Commands -------- Commands read and write external files and are marked by double bars (||) at the beginning of a line. Command parameters are separated by a single bar (|). In the summary below parameter options are separated with semi-colons, parameter list elements are separated with commas, and options are in parenthesis. File locations are specified using shortene, relative paths that include the name of the file and the name of its containing folder. Folder organization is described [here](/organize.md#folders) {list-table} :header-rows: 1 * - command [applicable API] * - || **text** | relative path | rivt; plain [R I V] * - The text command inserts and formats plain text files or files with rivt tags. * - || **append** | relative path | cover.pdf [R] * - The append command attaches PDF files to the end of the doc. * - || **image** | relative path, (2nd path) | width, (width) [I] * - The image command inserts and formats png or jpg files. * - || **table** | relative path | max col width, align [I] * - The table command inserts and formats tabular data from csv or xls files. * - || **declare** | relative path | print; noprint [V] * - The declare command imports values from a csv file written by rivt. Used for passing calculation results between documents. Tags ---- Line tags format a line of text and are denoted with *_[tag]*, typically at the end of a line. The *=* and *:=* tags used in the Value method are unique exceptions. {list-table} :header-rows: 1 * - line tags - description - API * - text _[b] - bold - R I V * - text _[c] - center - R I V * - text _[i] - italic - R I V * - text _[bc] - bold-center - R I V * - text _[bi] - bold-italic - R I V * - text _[r] - right justify - R I V * - text _[u] - underline - R I V * - text _[l] - LaTeX math - I V * - text _[s] - sympy math - I V * - text _[bs] - bold-sympy math - I V * - text _[e] - equation label, autonumber - I V * - text _[f] - figure caption, autonumber - I V * - text _[t] - table title, autonumber - I V * - text _[#] - footnote, autonumber - I V * - text _[d] - footnote description - I V * - _[page] - new page - I V * - _[address, label] - url or internal reference - I V * - a = 1.2 | unit, alt | descrip - declare = - V * - a := b + c | unit, alt | n,n - assign := - V Block tags start a text block with *_[[tag]]* and end with *_[[q]]*. {list-table} :header-rows: 1 * - block tags - description - API * - _[[b]] - bold - R I V * - _[[c]] - center - R I V * - _[[i]] - italic - R I V * - _[[p]] - plain - R I V * - _[[q]] - quit block - R I V * - _[[l]] - LaTeX - I V Profiles -------- The rivt VSCode profile includes extensions, snippets and shortcuts for common editing functions. ============== =========================================================== Keystroke Description ============== =========================================================== alt+q rewrap paragraph with hard line feeds (80 default) alt+p open file under cursor alt+. select correct spelling under cursor alt+8 insert date alt+9 insert time ctl+1 focus on first editor ctl+2 focus on next editor ctl+3 focus on previous editor ctl+8 focus on explorer pane ctl+9 focus on github pane ctl+alt+x reload window ctl+alt+u unfold all code ctl+alt+f fold code level 2 (rivt sections visible) ctl+alt+a fold code - all levels ctl+alt+t toggle local fold ctl+alt+e toggle explorer sort order ctl+alt+s toggle spell check ctl+alt+g next editor group ctl+shift+u open URL under cursor in browser ctl+shift+s open GitHub rivt README search ctl+shift+a commit all ctl+shift+z commit current editor ctl+shift+x post to remote snippets -------- | **snippet** | :---------: | ini | app | img | tbl | dec | txt command snippets ---------------- some text GitHub ------ some text :: import rivtlib.rivtapi as rv rv.R("""Introduction | notoc, 1 The Repo method (short for repository and report) is the first method of a rivt file which specifies document configuration settings. The first line of any method is the heading line, which starts a new document section. If the section heading is preceded by two dashes (--) it becomes a section reference and a new section is not started. The toc parameter specifies whether a document table of contents is generated (not to be confused with a report table of contents). The page number is the starting page number for the doc when processed as a stand alone document. The init command specifies the name of the configuration file which is read from the rivt-doc folder. Report formatting can be easily modified by specifying a different init file. ||init | rivt01.ini The text command inserts text from an external file. Text files may be plain text or include rivt tags. ||text | private/text/proj.txt | plain The append command attaches PDF files to the end of the doc. || append | append/report1.pdf || append | append/report2.pdf """) rv.I("""The Insert method | default The Insert method formats static information e.g. images and text. The color command specifies a background color for the section. The text command inserts and formats text from external files into the rivt file. Text files may be plain text or text with rivt tags. ||text | data0101/describe.txt | rivt The table command inserts and formats tabular data from csv or xls files. The _[t] tag formats and autonumbers table titles. A table title _[t] || table | data0101/file.csv | 60,r The image command inserts and formats image data from png or jpg files. The _[f] tag formats and autonumbers figures. A figure caption _[f] || image | data0101/f1.png | 50 Two images may be placed side by side as follows: The first figure caption _[f] The second figure caption _[f] || image | private/image/f2.png, private/image/f3.png | 45,35 The tags _[x] and _[s] format LaTeX and sympy equations: \gamma = \frac{5}{x+y} + 3 _[x] x = 32 + (y/2) _[s] """) rv.V("""The Values method | sub; nosub The Values method assigns values to variables and evaluates equations. The sub; nosub setting specifies whether the equations are printed a second time with substituted numerical values. A table tag provides a table title and number. The equal tag declares a value. A sequence of declared values terminated with a blank line are formatted as a table. Example of assignment list _[t] f1 = 10.1 * LBF | N | a force d1 = 12.1 * IN | CM | a length An equation tag provides an equation description and number. A colon-equal tag assigns a value and specifies the result units and printed output decimal places in the result and equation. Example equation - Area of circle _[e] a1 := 3.14(d1/2)^2 | IN^2, CM^2 | 1,2 || declare | data0102/values0102.csv The declare command imports values from a csv file written by rivt when processing assigned and declared values from another doc in the same project. """) rivt ---- **rivt** is a lightweight markup language for writing, organizing and sharing engineering documents and reports. It is designed to be legible, flexible and efficient. **rivt** is also the name of an open source framework used for producing rivt documents. **rivtlib** is a Python library that processes rivt files and is distributed under the open source MIT license. It runs on platforms that support Python 3.11 or later and works within a framework of five established, open souce technologies: - Language: Python with open source libraries including **rivtlib** - IDE: VSCode and extensions - Typesetting: Latex TexLive Distribution - Diagrams: QCAD - Version control: GitHub The **rivt** framework can be downloaded as a portable Windows zip file or installed through OS specific shell scripts (https://rivtcode.net). It is also available as an online service at https://rivtonline.net. A rivt document (doc) is a text, HTML or PDF ouput file from a processed rivt file. A rivt report (report) is an organized collection of rivt docs. **rivtlib** organizes and generates both large reports and single file docs. A rivt file is a Python file that imports **rivtlib** and its 6 API functions: *import rivtlib.rivtapi as rv* # where rS is a triple quoted Python rivt-string rv.R(rS) - (Run) Run shell scripts rv.I(rS) - (Insert) Insert static text, images, tables and math equations rv.V(rS) - (Values) Evaluate tables, values and equations rv.T(rS) - (Tools) Execute Python functions rv.X(rS) - (eXclude) Skip rivt-string processing rv.W(rS) - (Write) Write formatted rivt documents The 6 API functions implement: - wrapper for reStructuredText markup (see https://quickrestructuredtext.com) - a folder and file structure - commands and tags for processing files and formatting output **rivt** commands and tags are summarized below. See the user manual at https://rivtdocs.net for futher details. Tags: formatting ----------------- Tags evaluate and format rivt strings. Line tags are inserted at the end of a line and block tags at the start and end of a text block. reStructuredText markup may also be used for formatting (see https://quickrestructuredtext.com). ===================== ========= ========================== ================== tags scope description API scope ===================== ========= ========================== ================== text _[u] line underline I text _[r] line right justify I text _[c] line center I text _[bc] line bold center I text _[bi] line bold italic I title _[t] line table title I equation _[s] line sympy math equation I equation _[x] line latex math equation I equation _[bs] line bold numbered sympy I equation _[bl] line bold numbered latex I _[[p]] block start monospace block I _[[l]] block start LaTeX block I _[[e]] block end block I label _[t] line lookup table title V title _[v] line value table title V label _[e] line equation label V var :=, a line declare value V var = a + b line assign value V text _[f] line numbered figure V,I text _[#] line footnote (autonumber) V,I text _[d] line footnote description V,I _[page] line new page V,I ===================== ========= ========================== ================== Commands: file processing -------------------------- rivt commands process files e.g. image, equations, tables etc. They start with a single or double bar (| or ||) and have the form: | (--) label or title (tag) | /relative/path/file.typ(:start-end) | params where options are shown in parenthesis and parameters depend on the file type. A leading double bar (||) optionally inserts the referenced file lines into the input for legiblity and checking. Command are shown below in the context of an API function. Within VSCode an API function or sequence of functions may be run interactively using the standard cell decorator *# %%*. Interactive output is formatted as utf-8 text, as is output to stdout when a rivt file is run from a terminal. ================================================================================ Command Overview ================================================================================ :: rv.R("""run function label | pass;redact | color;none The Run function processes shell commands. | run | | capture | | edit | """) rv.I("""Insert Function Label | pass;redact | color;none The Insert function formats static file objects including equations, images, tables and text. | append label | /append/path/.pdf | number; nonumber | equation label (_[s,l]) | /text/path/.tex;txt(:start-end) | bold; plain | image label (_[i]) | /image/path/.jpg;.png;.svg | size, color | table title (_[t]) | /tables/path/.csv;.xls (:start-end) | width, align | text label | /text/path/.txt(:start-end) | plain; rivt """) rv.V("""Values Function Label | pass;redact | color;none The Values function evaluates lookup tables, variables and equations from files. | image label (_[i])| /image/path/.jpg;.png;.svg | size, color | table title (_[t])| /tables/path/.csv;.xls (:start-end) | [cols] | value label (_[v])| /values/path/.csv(:start-end) | | equation label (_[e]) | /values/path/.txt(:start-end) | ref; noref """) rv.T("""Tools function label | pass;redact | color;none The Tools function imports and evaluates functions. | function label (_[f]) | /scripts/path/.py | function name; file f1(x) """) rv.X(""" | | The X function prevents evaluation of the function. Any API function may be changed to X for flow control, testing, debugging and comments. """) rv.W("""Write function label | pass;redact | color;none The Write function generates a formatted doc file from a rivt file as text, HTML and PDF. It generates reports based on config file settings as README.txt, HTML and PDF. | output | files """) Folders: document organization ------------------------------ **rivt** implements a file and folder structure to simplify file sharing and control. The privacy level of document inputs and outputs may be may be set at the file or API function level. Each rivt file (and doc) is idenfiifed by a unique rivt file prefix with the form rivddss-filename where dd is a two digit division number and ss is a two digit subdivision number e.g., riv0203-loads.py is the third subdivision of division two. Editing the rivt number also changes the report organization. Report and document headings are taken from folder and file names unless overridden in the config file. An example folder structure is shown below. Required file names or prefixes are shown in [ ]. Source files for rivt docs are stored in 6 folders:: - append - images - scripts - tables - text - values Output is written to the write folder with 4 sub-folders:: - html - pdf - text - temp - xrivt Doc files are the text, PDF or HTML output of a rivt file that are stored in the *write* folder. rivt reports are collections of docs specified in the config.ini. Resource files are stored in user-defined sub-folders which organize the data allow for separation of public and private data. :: [rivt]-Project-Name/ ├── [append]/ ├── app01/ └── app02/ ├── attach3.pdf └── attach4.pdf ├── [images]/ ├── img01/ └── img02/ ├── image3.jpg └── image4.jpg ├── [scripts]/ ├── py01/ └── py02/ ├── function3.py └── function4.py ├── run01/ └── run02/ ├── script3.bat └── script4.sh ├── [tables]/ ├── tbl01/ └── tbl02/ ├── table3.csv └── table4.csv ├── [text]/ ├── tex01/ ├── tex02/ ├── latex3.tex └── latex4.tex ├── txt01/ └── txt02/ ├── text3.txt └── text4.txt ├── [values]/ ├── dat01/ ├── dat02/ ├── table3.csv └── table4.csv ├── equ01/ ├── equ02/ ├── equation1.txt └── equation2.txt ├── val01/ └── val02/ ├── values3.csv └── values4.csv ├── [write]/ (output files) ├── [html]/ └── riv0101-codes.html (html files) riv0202-frames.html Project-Name.html (html report) ├── [pdf]/ └── riv0101-codes.pdf (pdf files) riv0202-frames.pdf Project-Name.pdf (pdf report) ├── [temp]/ (temp files) └── temp-files.tex └── [text]/ └── riv0101-codes.txt (text output) riv0201-frames.txt └── [xrivt-redacted]/ └── README.txt (redacted report) xriv0101-codes.py (redacted files) xriv0102-loads.py xriv0201-walls.py └── config.ini (rivt config file) README.txt (searchable report in public repo) riv0000-report.py (rivt input files) riv0101-codes.py riv0102-loads.py riv0201-walls.py riv0202-frames.py Example rivt file ----------------------------------------------------------------------------- API functions start in column one. rivt-strings are indented four spaces (for legibility and code folding).A rivt doc is assembled by each function in order of the input order. Each function also, optionally, defines a doc section. :: import rivtlib.rivtapi as rv rv.R("""Run function | pass; redact | nocolor; color code The Run function processes shell commands. Each API function defines a new document section. The first line is a heading line which includes the section heading, a parameter for redacting sections in a mirror file intended for public sharing, and a parameter for the background color for the section. If the section heading is preceded by two dashes (--) the section is continued from the prior section without introducting a new number. File formatting follows pep8 and ruff. API functions start in column one. All other lines are indented 4 spaces to facilitate section folding, bookmarks and legibility. """) rv.I("""Insert function | pass; redact | nocolor The Insert function formats static objects including images, tables, equations and text. ||text | data01/describe.txt | rivt The table command inserts and formats tabular data from csv or xls files. The _[t] tag formats and autonumbers table titles. A table title _[t] || table | data/file.csv | 60,r The image command inserts and formats image data from png or jpg files. The _[f] tag formats and autonumbers figures. A figure caption _[f] || image | data/f1.png | 50 Two images may be placed side by side as follows: The first figure caption _[f] The second figure caption _[f] || image | private/image/f2.png, private/image/f3.png | 45,35 The tags _[x] and _[s] format LaTeX and sympy equations: \gamma = \frac{5}{x+y} + 3 _[x] x = 32 + (y/2) _[s] """) rv.V("""Values function | pass; redact | nocolor The Values fucntion evaluates variables and equations. The equal tag declares a value. A sequence of declared values terminated with a blank line is formatted as a table. Example of assignment list _[t] f1 = 10.1 * LBF |LBF, N| a force value d1 = 12.1 * IN |IN, CM| a length value An equation tag provides an equation description and number. A colon-equal tag assigns a value and specifies the result units and the output decimal places printed in the result and equation. Example equation - Area of circle _[e] a1 := 3.14(d1/2)^2 | IN^2, CM^2 | 1,2 || declare | data01/values02.csv The declare command imports values from the csv file written by rivt when processing values in other documents. """) rv.T("""Tools function | pass; redact | nocolor The Tools function processes Python code. """) rv.X("""Any text Changing a function to X skips evaluation of that function. Its purposes include review commenting and debugging. """) rv.W("""Write function | pass; redact | nocolor The Write function generates docs and reports. | docs | | report | """) VSCode profile ----------------------------------------------------------------------------- ============== ============================================================== Snippets/Keys description ============== ============================================================== run API Run function ins API Insert function val API Values function too API Tools function wri API Write function alt+q rewrap paragraph with hard line feeds (80 default) alt+p open file under cursor alt+. select correct spelling under cursor alt+8 insert date alt+9 insert time ctl+1 focus on first editor ctl+2 focus on next editor ctl+3 focus on previous editor ctl+8 focus on explorer pane ctl+9 focus on github pane ctl+alt+x reload window ctl+alt+[ reload window ctl+alt+] unfold all code ctl+alt+u unfold all code ctl+alt+f fold code level 2 (rivt sections visible) ctl+alt+a fold code - all levels ctl+alt+t toggle local fold ctl+alt+e toggle explorer sort order ctl+alt+s toggle spell check ctl+alt+g next editor group ctl+shift+u open URL under cursor in browser ctl+shift+s open GitHub README search for rivt ctl+shift+a commit all ctl+shift+z commit the current editor ctl+shift+x post to remote ============== ============================================================== ============================================== =============================== Extensions description ============================================== =============================== BUTTONS . tombonnike.vscode-status-bar-format-toggle format button gsppvo.vscode-commandbar command buttons AdamAnand.adamstool command buttons nanlei.save-all save all button Ho-Wan.setting-toggle toggle settings yasukotelin.toggle-panel toggle panel fabiospampinato.vscode-commands user command buttons jerrygoyal.shortcut-menu-bar menu bar EDITING . henryclayton.context-menu-toggle-comments toggle comments TroelsDamgaard.reflow-paragraph wrap paragraph streetsidesoftware.code-spell-checker spell check jmviz.quote-list quote elements in a list njpwerner.autodocstring insert doc string oijaz.unicode-latex unicode symbols from latex jsynowiec.vscode-insertdatestring insert date string janisdd.vscode-edit-csv csv editor VIEWS . GrapeCity.gc-excelviewer excel viewer SimonSiefke.svg-preview svg viewer tomoki1207.pdf pdf viewer RandomFractalsInc.vscode-data-preview data viewing tools Fr43nk.seito-openfile open file from path vikyd.vscode-fold-level line folding tool file-icons.file-icons icon library tintinweb.vscode-inline-bookmarks inline bookmarks MANAGEMENT . alefragnani.project-manager folder, project management Anjali.clipboard-history clipboard history dionmunk.vscode-notes notepad hbenl.vscode-test-explorer test explorer mightycoco.fsdeploy save file to second location lyzerk.linecounter count lines in files sandcastle.vscode-open open files in default app zjffun.snippetsmanager snippet manager spmeesseman.vscode-taskexplorer task explorer GITHUB . GitHub.codespaces run files in codespaces GitHub.remotehub run remote files ettoreciprian.vscode-websearch search github within VSCode donjayamanne.githistory git history MichaelCurrin.auto-commit-msg git auto commit message github.vscode-github-actions github actions GitHub.vscode-pull-request-github github pull request k9982874.github-gist-explorer gist explorer vsls-contrib.gistfs gist tools PYTHON . ms-python.autopep8 python pep8 formatting ms-python.isort python sort imports donjayamanne.python-environment-manager python library list ms-python.python python tools ms-python.vscode-pylance python language server ms-toolsai.jupyter jupyter tools ms-toolsai.jupyter-keymap jupyter tools ms-toolsai.jupyter-renderers jupyter tools ms-toolsai.vscode-jupyter-cell-tags jupyter tools ms-toolsai.vscode-jupyter-slideshow jupyter tools LANGUAGES . qwtel.sqlite-viewer sqlite tools RDebugger.r-debugger R tools REditorSupport.r R tools ms-vscode-remote.remote-wsl windows linux tools James-Yu.latex-workshop latex tools lextudio.restructuredtext restructured text tools trond-snekvik.simple-rst restructured syntax yzane.markdown-pdf markdown to pdf yzhang.markdown-all-in-one markdown tools ============================================== ===============================