docs: use mkdocs and mkdocs-material theme for klipper3d.org [WIP]

[damlobster]

This is an alternative solution to PR #4327.

It uses mkdocs and mkdocs-material theme to render the site visible at klipper3d.org. The site is generated and deployed in the gh-pages branch by the github workflow klipper3d-deploy.yaml.

Here is the procedure to test the site locally:

1. install the python dependencies: pip install -r docs/_klipper3d/requirements.txt
2. build and serve the site: mkdocs serve --reload
3. Open http://127.0.0.1:8000/ in the browser

It also visible at: https://damlobster.github.io/klipper/

Note: changes will be needed to deploy it on klipper3d.org (CNAME, workflow)

[KevinOConnor]

I like it! I think it would be worthwhile to make this change, as it seems like a notable improvement on the docs.

Do you know what steps I'd need to make to complete this change? I'd need to change github to use the ghpages branch, do something with CNAME?, and is an api key still needed?

I saw a few minor things - all could be fixed after merge:

1. Oddly, the indent for "Rotation Distance" under "Config Reference" on the Overview page is no longer there.
2. FWIW, I find the "top nav" (with "Overview", "Configuration and Tuning", "Developer documentation", "Device specific documents") on full screen browsers to be confusing.
3. Super minor, but a few files have extra/missing newlines at the end.

Thanks for working on this.
-Kevin

[damlobster]

I also think it is a good improvement over the current documents and I find mkdocs much easier to use than Jekyll/JustTheDocs.

Regarding the points you raised:

1. Actually, this was a problem that occured in many other pages. It comes from the fact that mkdocs use python-markdown for the rendering and that its markdown flavor (CommonMark) is not exactly the same as the github one. It took me several trials and errors to get to a working solution that doesn't require modifications to md files. I used some python-markdown extensions and handled the remaining incompatibilities in the mkdocs hook (docs/_klipper3d/mkdocs_hooks.py).
2. Corrected (there are a lot of customization options available in mkdocs.yml).

I tried my best to do a side-by-side comparison of the old klipper3d site with the new one, but I can't guarantee that I've missed out on something. At least if there are still errors, they should be minimal and not fundamentally impact the markdown rendering.

The procedure for deploying the site should be quite simple: I updated the PR with www.klipper3d.org in the CNAME file and your google-analytic tag in mkdocs.yml. Normaly, the only thing you have to do is to change the branch used to serve the site from masterto gh_pages and it should work as is (no need for the GH_TOKEN).

If you want to try the deployment on klipper3d before merging this PR into master, you can test it in a new branch by updating the klipper3d-deploy.yaml:

name: klipper3d deploy
on:
  push:
    branches:
      - YOUR BRANCH NAME

[KevinOConnor]

Thanks! I merged this change and made a few minor documentation changes on top.

One thing I noticed after merging is that there is a new top-level file mkdocs.yml. Is it possible to move this file to the docs/_klipper3d/ directory (or docs/ )?

-Kevin

[damlobster]

Great!

I found a solution to move mkdocs.yml to docs/_klipper3d/mkdocs.yml. Here are the required changes: damlobster@4d708dd

[KevinOConnor]

Thanks! I applied that change (commit ba16c0f).

One other thing - we have a handful of cases where we pointed people to links like - https://www.klipper3d.org/Contact.html , which no longer work. The new link is https://www.klipper3d.org/Contact . Do you know if we can easily restore the old links?

-Kevin

[KevinOConnor]

Ah - I found the setting for using .html links and made the change (commit a17c2ae).

-Kevin

[KevinOConnor]

Thanks again - the new site is great!

I was thinking of making a change to the "section navigation" - the links on the left of the screen when the browser is in full screen mode. I'm finding the navigation to be a little confusing. It's good to be able to click on "Overview" to go to the Overview.html page, but it's confusing to click on "Device specific documents" and go to the Example_Configs.html link, for example. I'd say about half of the links make sense right now. Maybe removing the "mkdocs-section-index" plugin and simplifying the nav would be an option.

Do you have any thoughts on this?

-Kevin

[damlobster]

You’re right, some of the links in the navigation are a little bit confusing sometimes.

I think there are two options:

1. disable the section-index plugin, this will add an empty level and the user can click it to see the pages below. The problem is that for the Overview “section", there will be an Overview "folder" and an Overview link under it.
2. keep the section-index plugin and introduce an index page describing the content of the section where it is needed. This could perhaps be a more flexible solution.

The best thing to do is to test it locally. Unfortunately, I don't have my computer with me (I'll be back from vacation around mid-August), but if you don't want to wait, you can test your changes locally with this command:

cd klipper
mkdocs serve --config-file docs/_klipper3d/mkdocs.yml

This works very well and the browser automatically reloads the site when a file is modified. Sometimes there are errors in the console, but it's just a bug with the auto-reload.

I hope this helps!

Damien

[KevinOConnor]

Yeah - I've been testing changes locally - a really nice benefit of mkdocs. I've been using docker:

FROM ubuntu:20.04

RUN apt-get update && apt-get install -y virtualenv python-dev git vim build-essential
RUN useradd -ms /bin/bash kevin

USER kevin
RUN cd ~ && git clone https://github.com/KevinOConnor/klipper.git
RUN virtualenv ~/python-env && ~/python-env/bin/pip install -r ~/klipper/docs/_klipper3d/mkdocs-requirements.txt
#RUN cd ~/klipper && ~/python-env/bin/mkdocs serve --config-file docs/_klipper3d/mkdocs.yml -a 0.0.0.0:8000

I'll continue to play with it. Enjoy your vacation!

-Kevin

[KevinOConnor]

FYI, I updated the docs to not use section-index for now (commit bd0185c).

-Kevin