Final fixes

Author: aversey

.gitignore

@@ -128,3 +128,4 @@ target/
 # Mac
 .DS_Store
 
+/temp_dir

README.md

@@ -4,38 +4,62 @@ This is the source of the Hopsworks Documentation published at <https://docs.hop
 
 ## Build instructions
 
-### Step 1: Setup python environment
+We use `mkdocs` together with [`mike`]((https://github.com/jimporter/mike/) for versioning to build the documentation.
+We also use this two main mkdocs plugins: [`mkdocstrings`](https://mkdocstrings.github.io/) and [its Python handler](https://mkdocstrings.github.io/python/), and [`mkdocs-material`](https://squidfunk.github.io/mkdocs-material/) as the theme.
 
-Create a python 3.10 environment, using a python environment manager of your own choosing. For example `virtualenv` or `anaconda`.
+**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.
 
-### Step 2
+### 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**.
+
+### Step 1
 
-Clone this repository
+Clone this repository:
 
 ```bash
 git clone https://github.com/logicalclocks/logicalclocks.github.io.git
 ```
 
-### Step 3
-
-Install the required dependencies to build the documentation in the python environment created in the previous step.
+### Step 2
 
-**Note that {PY_ENV} is the path to your python environment.**
+Create a python virtual environment to build the documentation:
 
 ```bash
-cd logicalclocks.github.io
-{PY_ENV}/bin/pip3 install -r requirements-docs.txt
+uv venv
+uv pip install -r requirements-docs.txt
+# Install hopsworks-api for gathering docstrings for the API reference
+uv pip install git+https://github.com/logicalclocks/hopsworks-api.git@main#subdirectory=python
 ```
 
-### Step 4
+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`).
 
-Use mkdocs to build the documentation and serve it locally
+### Step 3
+
+Build and serve the docs using mike.
 
 ```bash
-{PY_ENV}/bin/mkdocs serve
+# Use the current version instead of 4.4:
+mike deploy 4.4 latest --update-alias
+# Next, serve the docs to access them locally:
+mike serve
 ```
 
-The documentation should now be available locally on the following URL: <http://127.0.0.1:8000/>
+**Important**: The first time you serve the docs, you have to choose a default version, as follows:
+
+```bash
+mike set-default latest
+```
 
 ## Adding new pages
 
@@ -57,85 +81,3 @@ linkchecker http://127.0.0.1:8000/
 # If ok just kill the server
 kill -9 $SERVER_PID
 ```
-
-## Setup and Build Documentation
-
-We use `mkdocs` together with `mike` ([for versioning](https://github.com/jimporter/mike/)) to build the documentation and a plugin called `keras-autodoc` to auto generate Python API documentation from docstrings.
-
-**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:
-
-- current master branches (e.g. of hopsworks corresponding to master of Hopsworks): rendered as current Hopsworks snapshot version, e.g. **4.0.0-SNAPSHOT [dev]**, where `dev` is an alias to indicate that this is an unstable version.
-- the latest release: rendered with full current version, e.g. **3.8.0 [latest]** with `latest` alias to indicate that this is the latest stable release.
-- previous stable releases: rendered without alias, e.g. **3.4.4**.
-
-### 4. Build Instructions
-
-For this you can either checkout and make a local copy of the `upstream/gh-pages` branch, where `mike` maintains the current state of docs.hopsworks.ai, or just build documentation for the branch you are updating:
-
-Building *one* branch:
-
-Checkout your dev branch with modified docs:
-
-```bash
-git checkout [dev-branch]
-```
-
-Generate API docs if necessary:
-
-```bash
-python auto_doc.py
-```
-
-Build docs with a version and alias
-
-```bash
-mike deploy [version] [alias] --update-alias
-
-# for example, if you are updating documentation to be merged to master,
-# which will become the new SNAPSHOT version:
-mike deploy 4.0.0-SNAPSHOT dev --update-alias
-
-# if you are updating docs of the latest stable release branch
-mike deploy [version] latest --update-alias
-
-# if you are updating docs of a previous stable release branch
-mike deploy [version]
-```
-
-If no gh-pages branch existed in your local repository, this will have created it.
-
-**Important**: If no previous docs were built, you will have to choose a version as default to be loaded as index, as follows
-
-```bash
-mike set-default [version-or-alias]
-```
-
-You can now checkout the gh-pages branch and serve:
-
-```bash
-git checkout gh-pages
-mike serve
-```
-
-You can also list all available versions/aliases:
-
-```bash
-mike list
-```
-
-Delete and reset your local gh-pages branch:
-
-```bash
-mike delete --all
-
-# or delete single version
-mike delete [version-or-alias]
-```

mkdocs.yml

@@ -379,5 +379,5 @@ markdown_extensions:
   - pymdownx.tasklist:
       custom_checkbox: true
   - pymdownx.emoji:
-      emoji_index: "!!python/name:material.extensions.emoji.twemoji"
-      emoji_generator: "!!python/name:material.extensions.emoji.to_svg"
+      emoji_index: !!python/name:material.extensions.emoji.twemoji
+      emoji_generator: !!python/name:material.extensions.emoji.to_svg