Hopsworks Documentation

This is the source of the Hopsworks Documentation published at https://docs.hopsworks.ai.

Build instructions

We use mkdocs together with mike for versioning to build the documentation. We also use this two main mkdocs plugins: mkdocstrings and its Python handler, and mkdocs-material as the theme.

Background about mike: mike builds the documentation and commits it as a new directory to the gh-pages branch. Each directory corresponds to one version of the documentation. Additionally, mike maintains a json in the root of gh-pages with the mappings of versions/aliases for each of the directories available. With aliases, you can define extra names like dev or latest, to indicate stable and unstable releases.

Versioning on docs.hopsworks.ai

On docs.hopsworks.ai we implement the following versioning scheme:

• the latest release: rendered with full current version, e.g. 4.4 [latest] with latest alias to indicate that this is the latest stable release.
• previous stable releases: rendered without alias, e.g. 4.3.
• development version: it is built using main branches and is hidden from the version selector, but it is still accessible at https://docs.hopsworks.ai/dev.

Step 1

Clone this repository:

git clone https://github.com/logicalclocks/logicalclocks.github.io.git

Step 2

Create a python virtual environment to build the documentation. Dependencies are declared in pyproject.toml and the project requires Python 3.13 (matching CI):

# Make sure Python 3.13 is available — uv can install it for you:
uv python install 3.13
# If your `uv` is a pyenv shim and the above fails, install 3.13 via pyenv first
# (`pyenv install 3.13` then `pyenv shell 3.13`) so uv resolves to the right interpreter.

uv sync
# Install hopsworks-api for gathering docstrings for the API reference
uv pip install git+https://github.com/logicalclocks/hopsworks-api.git@main#subdirectory=python

Alternatively, you can just activate the virtual environment you use for development of hopsworks-api (obtained via uv sync), this is the way it is done in the actions. Namely, in .github/workflows/mkdocs-release.yml and .github/workflows/mkdocs-test.yml, the hopsworks-api repo is cloned, and its uv virtual environment is used with dev extra and all development groups.

A callback is set in hopsworks-api GitHub Actions, which triggers .github/workflows/mkdocs-release.yml on any pushes to release branches (that is, branch-x.x).

Step 3

Build and serve the docs using mike. Prefix every command with uv run so it picks up the binaries installed by uv sync into .venv/bin/. Local mkdocs/mike builds also need docs/javadoc to exist (it's generated by CI from hopsworks-api's Java sources), so touch it first and clean up after.

For a plain live-preview (no versioning), the quickest dev loop is:

touch docs/javadoc && uv run mkdocs serve --livereload

For the full mike workflow:

touch docs/javadoc

# Use the current version instead of 4.4:
uv run mike deploy 4.4 latest --update-alias
# Next, serve the docs to access them locally:
uv run mike serve

# Clean up when done:
rm docs/javadoc

Important: The first time you serve the docs, you have to choose a default version, as follows:

uv run mike set-default latest

Adding new pages

The mkdocs.yml file of this repository defines the pages to show in the navigation. After adding your new page in the docs folder, you also need to add it to this file for it to show up in the navigation.

Checking links

linkchecker is in the dev dependency group of pyproject.toml, so it is installed by uv sync and can be invoked via uv run.

touch docs/javadoc
# run the server
uv run mkdocs serve > /dev/null 2>&1 &
SERVER_PID=$!
echo "mk server in PID $SERVER_PID"
# Give enough time for serving
sleep 30
echo "Launching linkchecker"
uv run linkchecker http://127.0.0.1:8000/

# If ok just kill the server
kill -9 $SERVER_PID
rm docs/javadoc