bottom/docs
Clement Tsang dab4b6c483
other: master -> main (#1349)
* other: master -> main

I'm so used to using `main` branch now that it's actually kinda annoying
to use `master` for just this repo... so might as well rename it now.

* overzealous change

* wording

* some wording

* allow auto-cancel for tests if not main
2023-12-06 00:16:26 -05:00
..
content other: master -> main (#1349) 2023-12-06 00:16:26 -05:00
.gitignore docs: adjust dev doc file structure, add build and deploy docs (#804) 2022-09-12 04:14:19 -04:00
mkdocs.yml other: master -> main (#1349) 2023-12-06 00:16:26 -05:00
README.md docs: add script to serve mkdocs locally 2023-02-04 04:58:16 -05:00
requirements.txt docs: bump mike to v2.0.0 (#1318) 2023-11-16 03:17:21 -05:00
serve.sh docs: bump mike to v2.0.0 (#1318) 2023-11-16 03:17:21 -05:00

Extended Documentation

This is where the extended documentation resides, hosted on GitHub Pages. We use MkDocs, Material for MkDocs, and mike.

Documentation is currently built using Python 3.11, though it should work fine with older versions.

Running locally

One way is to just run serve.sh. Alternatively, the manual steps are:

# Change directories to the documentation.
cd docs/

# Create and activate venv.
python -m venv venv
source venv/bin/activate

# Install requirements
pip install -r requirements.txt

# Run mkdocs
venv/bin/mkdocs serve

Deploying

Deploying is done via mike.

Nightly

cd docs
mike deploy nightly --push

Stable

cd docs

# Rename the previous stable version
mike retitle --push stable $OLD_STABLE_VERSION

# Set the newest version as the most recent stable version
mike deploy --push --update-aliases $RELEASE_VERSION stable

# Append a "(stable)" string to the end.
mike retitle --push $RELEASE_VERSION "$RELEASE_VERSION (stable)"