Hyperview Documentation

Hyperview documentation is written in MyST a Markdown variant designed for technical documentation and scientific communication. The site generator is Sphinx.

Quickstart

The following steps assume that you are using a package manager such as scoop, apt, dnf or brew installed.

• Install Python 3, NodeJS-LTS and Make using your favorite package manager.

For example, on Microsoft Windows run the following commands:

scoop install python
scoop install nodejs-lts
scoop install make

• Initialize a virtual environment in the root of the repository.

NOTE: bash (git-bash on Microsoft Windows) is the recommended shell environment.

python3 -m venv .

• Activate virtual environment

# Linux, WSL, MacOS, Git-bash
source bin/activate

• Install Sphinx and Redoc CLI; Using your favorite console app, run the following command from the repository root.

make setup

NOTE: All subsequent Make commands must be run from the repository root.

• To make the HTML version of the documentation run the following command.

make site

• To browse the site on your machine, you need to have Docker installed. Then run the following commands.

# To build the local docker container
make docker_build

# To stop and clean the local docker container (if needed)
make docker_stop

# To start the docker container
make docker_start

• Navigate to localhost:8080 to browse the docs site.

API Changes

We use a tool called openapi-diff from the openapitools project.

Editing documentation

Use your favorite text or code editor. For VSCode the instructions are below.

• Install Visual Studio Code

• Install Visual Studio Code Extension: EditorConfig for VS Code

• Install Visual Studio Code Extension: Code Spell Checker

• Install Visual Studio Code Extension: MyST-Markdown

Resources

• MyST
• MyST Parser
• Sphinx Project