A.1 Start

[1t] Run examples

---

An overiew of rivt can be found here. This section reviews how to get started in writing rivt files and publishing rivt docs

rivt file examples can be run in the cloud or on a local computer. In both cases editing and publishing is typically carried out in an IDE. The rivt framework includes VSCode, but any IDE may be used. A typical IDE layout can be viewed at Codesandbox. The sandbox allows scrolling through an example rivt file (left panel) and text doc (right panel). Files may be downloaded from the file explorer (far left panel) including the text, pdf and html reports. Because the is unregistered editor files cannot be edited or processed.

VSCode can be run locally or in the cloud. The cloud version is referred to as a Codespace . A rivt Codespace is a VSCode cloud environment with rivt extensions for editing and running rivt files. It can be forked (copied) and run in a personal GithUb account that may be set up here. A rivt Codepsace with examples can be forked from this repository by following the steps below.

Fork a *rivt Codespace* in the cloud

1. Click the Fork button in the upper right corner.
    This creates a copy of the repository in your GitHub account.
2. Switch to your GitHub account and open the forked repository
3. Click the green Code button
4. Select the Codespaces tab
5. Click the rivt-codespace-examples option.
6. This creates a Codespace environment in your GitHub account
    and opens the repository in the online VSCode IDE. The environment
    includes the rivt packages and extensions needed to run and
    publish rivt docs and files.

Local installation methods

1. Windows portable zip folder ([2t] rivt-portable) rivt-portable is recommended for Windows users unfamiliar with Python.

2. System Python ([3t] rivt-sys with uv) with or without uv manager (rivt-uv)

[2t] rivt-portable

---

A rivt-portable installation is recommended for Windows users unfamiliar with Python. rivt-portable is a zip file :

win64-rivt-portable-n.n.n[an].zip

where n is a number representing the major, minor and patch release number. An an appended to the version is an alpha release where users should expect that features are missing and rivt markup syntax may change in the future. Zip file contents must be unzipped into a directory with read-write access - typically the users home folder or a flash drive.

The zipped and unzipped file sizes include the following contents and are approximately 1GB and 2GB respectively:

release: rivt-portable-1.0.0a4.zip

1. Python 3.14 with rivt packages
2. VSCode 1.109 with rivt extensions
3. rivt-1.1.0a4
4. Example rivt files

Releases may be download from the GitHub repository.

The primary advantages of rivt-portable are

1. simplified installation

2. package integration

3. isolation from system files.

After unzipping, VSCode and examples are started with a single shortcut.

The primary disadvantages of rivt-portable are that rivt packages and extensions must be updated by updating the zip file as a whole, and it is more difficult to integrate with other Python programs.

[3t] rivt-sys with uv

---

rivt may be installed at the system level.

1. Install Python using Python installers if not already installed. The minimum version required by rivt is Python 3.13.

2. Install rivtlib and dependencies using pip

pip install rivtlib

A list of the dependencies is here.

rivt-uv

Rather than installing rivtlib at the system level, it can be installed in an isolated environment using the uv package manager. The primary advantage of rivt-uv is the simplicity of updating packages while keeping them isolated from the system Python.

rivt-uv installation is recommended for users with some familiarity with Python and programming.

Step 1. Install uv

Different methods for installing uv are described here.

The recommended method for installing uv is from the command line:

Windows:

winget install --id=astral-sh.uv  -e

macOS and Linux:

curl -LsSf https://astral.sh/uv/install.sh | sh

Step 2. Create the rivt environment

After installing uv, download and run the following rivt install script. It installs an isolated rivt environment and example files in a folder named rivt-examples in the users Home directory.

Windows: rivtuv.cmd

OSX and Linux: rivtuv.sh

Step 3. Run the example program from Pyzo.

The rivt environment is activated by:

Windows:

./venv/Scripts/activate

macOS and Linux:

source venv/bin/activate

rivt includes the Pyzo IDE for editing and running examples. Typing the command pyzo-example from the environment root will load the example file rv00-simple-doc.py where it can be edited and run.

The example file can also be run from the command line with the command:

python -m rivt rv001-single-doc.py

The uv environment can be completely removed with the following commands.

uv deactivate
rmdir /s /q rivt-examples
uv cache clean

[4t] rivt Framework

The full rivt framework may be integrated with rivt when it is installed at the system level, including uv. The framework includes:

1. VSCode IDE <https://code.visualstudio.com/> and

   extensions <https://marketplace.visualstudio.com/vscode>. rivt extensions and snippets are here.

2. Git file version control <https://git-scm.com>

3. GitHub file sharing <GitHub

4. LaTeX document formatting <https://www.tug.org/texlive/>

5. QCAD diagraming.