Mkdocs for the documentation

[susuhahnml]

No description provided.

[rkaminsk]

Just one small thing. I'll also give it a test run tomorrow.

[sthiele]

@susuhahnml Could we change the directory /docs/reference/api to /docs/reference/API to get the capitalization right?

[rkaminsk]

@susuhahnml Could we change the directory /docs/reference/api to /docs/reference/API to get the capitalization right?

Please lets stick to all lower case for filenames and urls.

[sthiele]

Please lets stick to all lower case for filenames and urls.

Could one use the nav section in the mkdocs.yml file?

[rkaminsk]

Please lets stick to all lower case for filenames and urls.

Could one use the nav section in the mkdocs.yml file?

Maybe there is another way to address this. Putting the filename is a bit strange anyway. I would have expected that some meta info is used.

[rkaminsk]

I had a look regarding the navigation. It seems like mkdocs uses the filename fore auto-generated navitems and there is no way around. The only way is to specify the full navigation in mkdocs.yml, which is probably what we should do.

EDIT: I simply specified the nav.

[rkaminsk]

Another problem is that the frontmatter does not seem to be configured correctly for some pages.

EDIT: the problem seems to be the markdown formatter configured via precommit. We probably have to exclude the folder.

[rkaminsk]

@susuhahnml and @sthiele, please have a look whether this works for you.

[rkaminsk]

One last thing, the blue bar on top in dark mode looks kinda ugly.

[susuhahnml]

I was running away a bit from explicitly writing the navigation so that adding a file was enough and one less step. But I am also ok with keeping it as it gives us more flexibility. Regarding the color, we could use one of the default ones but I would also like to have something unique, since the default is used by many other systems. I also agree it does not look amazing in dark mode.

[susuhahnml]

I changed the color slightly, let me know if you like it better, I imagine that with the whole new branding we would ideally use whatever color is decided there. I also updated the readme with the -- serve for the docs

[rkaminsk]

@susuhahnml I applied one more tweak to the color. Feel free to refine further. And then just go ahead with merging.