Skip to content

Updating Documentation

The documentation is written in Markdown, this website is generated based on this Markdown content using Material for MkDocs and the documentation versioning is done with mike.

This website is hosted on GitHub Pages based on the gh-pages branch (i.e. the default GitHub Pages branch).

Updating based on main Branch

To update the current documentation based on the main branch:

  1. Install Material for MkDocs
  2. Run inside the local repo/installation folder of K2s:
    Bash Session
    mkdocs serve
  3. Open http://127.0.0.1:8000/K2s/ in your web browser to see your local changes being applied on-the-fly
  4. Submit your changes
  5. Wait for the automatically triggered workflow Build - Documentation (next) to finish
  6. 🚀 Your changes are now published to https://siemens-healthineers.github.io/K2s/next

Note

Since mkdocs serve does not take versioning into account, the following warning will appear in the console output: "GET /versions.json HTTP/1.1" code 404
This warning can safely be ignored. To test different documentation versions locally, see Documentation Versioning.

Documentation Versioning

To provide different versions of the generated documentation (e.g. a version per release and a current one matching the contents of the main branch), to tool mike can be utilized like described in the following:

If not done already, install mike:

Bash Session
pip install mike

To inspect all existing documentation versions on the gh-pages branch, run:

Bash Session
mike list

To add a new version, run:

Bash Session
mike deploy <version> [<alias>]

Example

To create a new version v1.2.3 with the tag latest, run:

Bash Session
mike deploy v1.2.3 latest
This will create a local commit to the gh-pages branch that still has to be pushed to origin.

Alternatively, mike can also create a new version and push the changes in one call with the -p or --pull parameter:

Bash Session
mike deploy v1.2.3 latest -p

To set a default version the user is redirected to when browsing the root URL:

Bash Session
mike set-default <version>|<alias>

Example

To set the default version to the one with the tag latest, run:

Bash Session
mike set-default latest

To delete a version, run:

Bash Session
mike delete <version>

To preview documentation versioning, run:

Bash Session
mike serve

Tip

mike serve is similar to mkdocs serve, but additionally takes versioning into account. On the other hand, mike's local dev server is extremely slow compared to mkdocs's built-in dev server so the recommendation is to use mkdocs serve for previewing changes to the documentation and mike serve for previewing changes to the versions.