A.0 | Start

[1] Getting Started

This section covers installation of rivt and rivt doc examples. As open source software you are free to download and modify the program as needed (see FAQ). The open source software installation process is built around the collection and management of the multiple open source components. This section covers three ways to install rivt.

1. For users unfamiliar with Python and open source software the simplest way to get started is to download the Windows portable zip file (~800 MB). It includes everything necessary to run and explore rivt. For further details see here.

2. For users with a GitHub account rivt can be forked and run in a browser using Codespaces. Further details are here.

3. For users familiar with Python, rivt may be installed at the OS level or in an isolated environment using uv. Further details are here.

[2] rivt IDE

rivt may be edited in a simple text processor and run from the command line but efficient editing and compiling is typically done in an IDE. Any IDE may be used but VSCode support is documented. A typical VSCode IDE layout editing a rivt file is shown below.

rivt files and docs in VSCode (click on image to enlarge)

A rivt file is a Python file (.py) that imports the rivtlib Python package and includes rivt markup. The rivt file is in the center editing panel[2], the doc outputs are in the right panel[3] and the file explorer is the far left panel [1]. Text, PDF and HTML output files are accessed in the file explorer and displayed within panels. Individual rivt sections (cells) can be run and output to an interactive terminal during doc development. Panel locations may be customized by the user. Additional example rivt files and docs are here.

---

[3] Portable rivt

A rivt-portable installation is recommended for Windows users unfamiliar with Python. rivt-portable is a zip file that includes the basic rivt framework.

The zip file naming convention is:

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 missing and incomplete features. The zip file contents must be unzipped into a directory with read-write access - typically the users home folder or a flash drive. After unzipping, VSCode and examples are started by clicking on the start-rivt.cmd file.

The primary features of rivt-portable are:

1. simplified, isolated installation

2. package and framework integration

3. installation needs to be updated as a whole, not as individual components.

4. integration with other programs may be more difficult.

Releases are updated monthly and may be downloaded from the GitHub repository.

---

[4] Codespace rivt

VSCode is a customizable code editor that can be run locally or in the cloud. The cloud version of VSCode 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) into a personal GitHub account. A rivt Codepsace can be forked from

by following the steps below. Example rivt files are included.

Fork a rivt Codespace

1. Set up a GitHub account if needed.

2. Go to the rivt Codespace repository

3. Click the Fork button in the upper right corner. This creates a copy of the repository in your GitHub account.

4. Switch to your GitHub account and naviate to the forked repository.

5. Click the green Code button.

6. Select the Codespaces tab.

7. Click the rivt-codespace-examples option.

8. This creates a Codespace environment in your GitHub account

   and opens the repository in the online VSCode IDE. The environment includes the rivt packages, extensions and examples.

---

[4] System rivt

rivt may be installed into a system level Python.

Step 1. Install Python

Install Python using Python installers if not already installed. The minimum required version is Python 3.14.

Step 2. install rivtlib and dependencies

Install rivtlib and dependencies using pip

pip install rivtlib

A list of the installed dependencies is here.

rivt may also be installed and isolated environment using the uv package manager. The primary advantage of uv is the simplicity of insalling and 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

---