A.1 Start

[1] Run examples

This section outlines steps for installing rivt and running examples. rivt is an open source project and, like all open source projects, is built from a variety of components written by many contributors. Most of the components are Python libraries but effective use of rivt also requires separate programs like the IDE VSCode. For a general overview of rivt start here.

There are three methods for installing and running *rivt* examples.

---

1. If you are not familiar with Python or programming, Portable-rivt is the recommended method. Portable-rivt is a single zip folder that contains a portable version of Python, rivt and VSCode with examples. The single Windows download requires no installation. Further details are given here

2. If you are familiar with GitHub and have an account you can run a cloud version of rivt in your browser using Codespace-rivt. Further details are described here.

3. Finally, if you are familiar with Python and want the most flexible and extensible environment, the recommended method is to install rivt at the system level in an isolated environment. System-rivt is described here.

---

[2] 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.

---

[3] Portable-rivt

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.

---

[4] Codespace-rivt

VSCode can be run locally or in the cloud. For local installation see [1] rivt 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 ([3] Portable-rivt) rivt-portable is recommended for Windows users unfamiliar with Python.

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

---

[4] System-rivt

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

---