Qlever Docs

Developing locally

1. Clone this repo
2. Setup a virtual environment with uv venv or python3 -m venv .venv and activate it . .venv/bin/activate
3. Install the dependencies with uv sync or pip install -e .
4. Run the development server mkdocs serve

---

Deployed docs: https://ad-freiburg.github.io/qlever-docs/

---

Categories of solutions:

1. general purpose static site generators with a suitable theme (Jekyll, Hugo/Doks/Hextra/Hugoblox Documentation Template/Docsy/Lotus Docs/More)
2. documentation tools built on JS frameworks (Docusaurus/React, VitePress/Vue, Docz (discontinued)/Gatsby)
3. purpose built solutions (MkDocs/Material for MkDocs, Gitbook)

I propose using MkDocs with the Material for MkDocs framework.

• MkDocs is a python based markdown static site generator with a focus on build documentation.
• Material for MkDocs is a framework on top of MkDocs for building documentations. Content is written in markdown. Configuration is done in a YAML file.

I think that this will provide more than enough features for us, without needing to much initial setup and we're still flexible, because the content is written in markdown.

Some Pros and Cons:

• easy to begin (!) and use
• large amount and diversity of features; most likely more than we'll ever need
• good documentation
• actively developed with some money behind it
• hard to extend beyond provided features