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 😉

[king-phyte]

@SMILEY4 We can merge this. I will get the gradle plugin in before the final release of v5

Edit: Wait. I got the gradle plugin to work
Now how do we deal with publishing both the Markdown and HTML for the API Reference? Any ideas? Because if I put the index.html in the nav, clicking on it takes you to the reference page and navigating back isn't ... obvious without using browser controls

[king-phyte]

Now the process is more like

./gradlew dokkaHtml
./gradlew mkdocsServe

I suppose what is left is adding CI/CD. But go ahead and try, and if the steps above work flawlessly, we can merge. I already have a sample workflow file

[SMILEY4]

Suggested change

	// Install the Op lugin and use the default configuration
	// Install the OpenApi Plugin and use the default configuration

[SMILEY4]

Hi.
I though i looked good enough to merge and we can then work on this in smaller more independent prs 👍

Did some testing regarding publishing the page.

./gradlew dokkaHtml
./gradlew mkdocsPublish -Porg.ajoberstar.grgit.auth.username=mygithubtoken

and it works 🥳 (almost) :
https://smiley4.github.io/ktor-swagger-ui/5.0-test.1/

two issues i found:

• for some reasons i could not get authentication to work with normal environment variables. Maybe i just missed something - it's not a big issue anyway.
• when viewing the latest version (https://smiley4.github.io/ktor-swagger-ui/latest/) and selecting the specific latest version from the dropdown it redirects to https://smiley4.github.io/ktor-swagger-ui/5.0-test.2/https://smiley4.github.io/ktor-swagger-ui/5.0-test.2/ instead of https://smiley4.github.io/ktor-swagger-ui/5.0-test.2/ resulting in a 404. I dont quite understand yet why that happens.

I'm also adding some additional notes to this pr as future todos so we don't forget.

[SMILEY4]

Maye remove badges from mkdocs wiki -> I think one of them results in some cookies associated with google analytics being set. I'm not 100% sure though about it, perhaps you could test it too and double check.

Firefox blocks it for me, though google chrome seems to allow it

[king-phyte]

I looked into it. It seems to be the Checks - Passing badge.

But that also reminds me, now that we have three packages instead of one, we may need to add the others to Maven Central if we still want to keep that too.

[king-phyte]

Hi. I though i looked good enough to merge and we can then work on this in smaller more independent prs 👍

Good idea

and it works 🥳 (almost) : https://smiley4.github.io/ktor-swagger-ui/5.0-test.1/

Excellent. I'm glad we at least made progress

for some reasons i could not get authentication to work with normal environment variables. Maybe i just missed something - it's not a big issue anyway.

Could you explain what you mean by normal environment variables?

when viewing the latest version (https://smiley4.github.io/ktor-swagger-ui/latest/) and selecting the specific latest version from the dropdown it redirects to https://smiley4.github.io/ktor-swagger-ui/5.0-test.2/https://smiley4.github.io/ktor-swagger-ui/5.0-test.2/ instead of https://smiley4.github.io/ktor-swagger-ui/5.0-test.2/ resulting in a 404. I dont quite understand yet why that happens.

The dropdown does not have latest, so to reproduce, I manually added it to the url, and indeed I saw what you are talking about. I think it may be related to the way I set up the site_url or the versioning. I will look into fixing it

I'm also adding some additional notes to this pr as future todos so we don't forget.

Another good idea. But it may be better to add it to #175 as that is still open. What do you think?