Use mkdocs-material for documentation

[king-phyte]

Closes #175

[king-phyte]

@SMILEY4 This is the PR for the documentation pages without the autogenerated API reference

If I were to make a list of the remaining tasks, it would be

• Add CI/CD to push pages on release
• Document how to run and preview the documentation locally (See this comment)
• Decide between using a gradle plugin (such as gradle-mkdocs-plugin) and using the Python workflow (i.e. do what the plugin is doing)
• Add autogenerated API reference with Dokka (sort of done, but I want to do one more pass)
• Decide on multi-version or single version documentation pages (See versioning)

[king-phyte]

How to run and preview the docs locally

Requirements

• Python (3.12 or 3.13 should be fine. Maybe use pyenv?)

Steps

Setting up environment

• Open the root of the project

• Create a virtual environment in the project root. Here, I use venv

  python -m venv .venv

• Activate the virtual environment

   source .venv/bin/activate

• Install dependencies

  pip install mkdocs-material

Previewing the docs

mkdocs serve

Autogenerated API Reference

To generate the API Reference, run

./gradlew dokkaJekyll

And run the command to preview the docs if it is not already running

For more information, see mkdocs-material

Possible future development

It is possible to use the gradle-mkdocs-plugin to manage the dependencies and environment as shown above, possibly reducing all the above discussed to something along the lines of

./gradlew mkdocsServe

or similar. We need to analyse the opportunity cost and make a decision

[SMILEY4]

Thank you!

I checked it out and it looks awesome already 👍

I did a quick test with dokka and tested the html output (./gradlew dokkaHtml) in comparison to Jekyll. I think i prefer the html output. It looks cleaner and more refined to me, though we would loose the "overall" styling and it would not look like the same page anymore.

What do you think?

Decide on multi-version or single version documentation pages (See versioning)

I think it would be great if we can get this to work, though I haven't quite understood yet how mike would work with our multiple step build process, i.e. dokka + mkdocs and publishing. I would probably need to do some more experiments myself.

Decide between using a gradle plugin (such as gradle-mkdocs-plugin) and using the Python workflow (i.e. do what the plugin is doing)

Assuming that the gradle task can do everything we need that would probably be the simplest solution. I doupt however that this would support our requirements with dokka, mkdocs and possibly mike. I dont think the python workflow is too complicated and probably allows for more flexibility for now.

Just let me know if you want to merge this branch and work with new ones or if you want to keep it open for a bit longer.

[king-phyte]

Thank you!

I checked it out and it looks awesome already 👍

Thank you 😄

I did a quick test with dokka and tested the html output (./gradlew dokkaHtml) in comparison to Jekyll. I think i prefer the html output. It looks cleaner and more refined to me, though we would loose the "overall" styling and it would not look like the same page anymore.

It does look nicer that way. And more "standard" for an API reference. How does it integrate with the rest of the Markdown files? I have to try it locally, I suppose.

I think it would be great if we can get this to work

Alright. I will try to get it to work.

though I haven't quite understood yet how mike would work with our multiple step build process, i.e. dokka + mkdocs and publishing. I would probably need to do some more experiments myself.

Basically, it would publish new versions into a subdirectory, and mike will allow switching versions when browsing the docs. I think maybe after I am done with that, you will understand it better

Assuming that the gradle task can do everything we need that would probably be the simplest solution. I doupt however that this would support our requirements with dokka, mkdocs and possibly mike. I dont think the python workflow is too complicated and probably allows for more flexibility for now.

I took another look at the plugin. Although the documentation is a bit lacking, it looks like it would allow us to do what we want to do by overriding certain things. I will give it a shot, and see what comes of that

Just let me know if you want to merge this branch and work with new ones or if you want to keep it open for a bit longer.

I wanted to decide on the Python vs Gradle plugin before merging. I will try and get the latter to work, but if it is proving challenging, we can go ahead and merge and maybe come back to it later

Also, maybe after this is all done, we can do something similar for the awesome kenerator 😉