A.1 Start

[1t] How to Run

---

This section explains how to get started in editing and running rivt file examples. Examples can be run in the cloud or on a local computer. In both cases editing is typically carried out in an IDE.

For a general overview of rivt start here.

The three methods for running rivt are:

1. Codespace-rivt runs the cloud and is described here

2. Portable-rivt-VSCode runs locally on Windows and is described here

3. System-rivt-uv runs locally and is described here

Codespace-rivt is recommended when local installation is not practical or desired and work is shared with teams. System installations are recommended for the most general and flexible implementation.

Portable-rivt-VSCode is recommended for Windows users unfamiliar with Python.

System-rivt-uv is recommended for users with some familiarity with Python and and provides the most flexible and extensible environment.

[2t] Typical IDE layout

rivt can be run from the command line but efficient editing and running of rivt files is typically done in an IDE. A typical IDE layout can be viewed at

Codesandbox.

This explorable browser example shows the rivt file in the left panel, the text doc output in the right panel or second tab, and the file explorer in the far left panel. Docs (txt, PDF and HTML output files) can be downloaded from the file explorer including the text, pdf and html reports. The IDE cannot be used to run files. Setting up a GitHub account and forking Codespace-rivt is needed.

[2t] Codespace-rivt

VSCode can be run locally or in the cloud. For local installation see [5t] Framework.

The cloud version is a Codespace . A rivt Codespace is a VSCode cloud environment with rivt extensions for editing and running rivt files. It can be forked (copied) into a personal GithUb account. Github setup is described here.

A rivt Codepsace can be forked from this repository by following the steps below. Example rivt files are included.

Fork a rivt Codespace

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 ([3t] Portable-rivt-vscode) rivt-portable is recommended for Windows users unfamiliar with Python.

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

[3t] Portable-rivt-vscode

---

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.

[4t] System-rivt-uv

---

rivt may be installed at the system level.

1. Install Python using Python installers The minimum version required by rivt is Python 3.14.

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

or

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex

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