Developer Install

This website is built by Github Actions with a Linux Ubuntu distribution using Quarto. You can replicate the same setup locally to run the tutorials, this will currently only work on Linux. See callout below to setup up Linux on your Windows machine using
WSL.

Pre-requisites

  • win-Key “Turn Windows features on or off”
  • ensure the following features are enabled:
    • Hyper-V
    • Windows Subsystem for Linux
    • Windows Hypervisor Platform
  • restart your computer. See
    GH issue troubleshooting
    for more details.

Setup Ubuntu Distribution with Pixi

# install Ubuntu distribution
wsl --install -d Ubuntu

# create a new user with a sensible username and password

# launches Ubuntu distribution (enters the linux bash shell)
wsl -d Ubuntu

# install pixi (package manager) - https://pixi.prefix.dev/latest/#installation
curl -fsSL https://pixi.sh/install.sh | bash

# Clone the repository
git clone https://github.com/wassimj/topologicpy.git

# Change directory
cd topologicpy

# list available tasks
pixi run

# launch jupyterlab in tutorials directory
pixi run lab-tutorials

Pixi Tasks

Common developer tasks are defined in the pixi.toml file. To see the available tasks:

pixi task list
Tasks that can run on this machine:

-----------------------------------

analyse-nb-imports, del-tutorials, download-openstudio, install-openstudio, lab, lab-tutorials, list-sidebar, mk-build-dir, open-tutorials, preview, test-energy, tests, tutorials

Task                 Description

analyse-nb-imports   analyse notebook imports

del-tutorials        delete built tutorials

download-openstudio  download OpenStudio for Ubuntu 24.04

install-openstudio   install OpenStudio on Ubuntu

lab                  open Jupyter Lab for notebooks

lab-tutorials        open Jupyter Lab for tutorials

list-sidebar         list sidebar contents from _quarto.yml

mk-build-dir         create build directory

open-tutorials       open built tutorials

preview              preview tutorials using Quarto

test-energy          run energy model import tests with dev env

tutorials            render tutorials using Quarto

Notes

  • To avoid duplication, Notebooks are copied from the notebooks directory to the tutorials directory when the Quarto website is built, such that the notebooks in the notebooks directory are the source of truth and the ones in the tutorials directory are generated.

  • By default in Quarto, Notebooks are not executed at build time and the saved outputs are used. Adding to the front matter of the notebook will enable execution at build time, this can serve as a test to ensure that the notebook is still working.

    execute:
  enabled: true

  • Alternatively, you can use .qmd files instead of .ipynb files for your notebooks where the output is not saved, and then the notebook output is generated at build time.