move to GitHub pages

[nilsnolde]

• moves the documentation to Github pages, see https://valhalla.github.io/valhalla/ (I pushed already and @kevinkreiser registered it in the settings)
• changes the theme to smth more modern than readthedocs theme (better navigation, vastly better search, dark mode)
• moves the MD files into ./docs/docs, which is necessary when we want to keep the mkdocs.yml in the docs directory, which I'd prefer
• adds some previously missing documents (e.g. incidents.md)
• adds a Github Action to deploy the docs on master pushes

@drewda would you mind removing the docs from readthedocs.io once this is merged? Then there won't be any ambiguity with a stale documentation still being live there.

[nilsnolde]

makes sure there's no warnings when building the docs, or the workflow will fail

[nilsnolde]

e.g. linking documents which don't exist (many of those previously)

[nilsnolde]

this is also ready for review/merge.

[kevinkreiser]

some are docs links like building above but this one and the run routes readme link to markdown on the master branch. this is a bit confusing to me. is it because docs generation doesn't docs-ify those? or should these markdown links be github.io docs-ified links?

[nilsnolde]

Right, it can't link them relatively because it doesn't have access to anything outside the ./docs/docs folder, see its branch: https://github.com/valhalla/valhalla/tree/gh-pages/. Symlinking wouldn't work here either, then the github.com version wouldn't find the right doc.

[nilsnolde]

Or well, with symlinking we could put the absolute URL of the GH Pages version. I don't really mind either way.

[kevinkreiser]

oh i just wondered if the make docs would turn the markdown into html to be rendered nicely without the built in github viewer but it seems like not? or maybe not by default? i am definitely not up to date on how the docs are generated. like why doesnt https://valhalla.github.io/valhalla/contributing get generated from the markdown? oh i see we have to change it in the yaml below and if we did that then we could have a nice html version of the markdown?

[nilsnolde]

if the make docs would turn the markdown into html to be rendered nicely without the built in github viewer

Oh yes, sure it does. If not, we couldn't verify locally. The "github viewer" doesn't do anything at all actually, other than pointing the URL to the right path on their server, the rest is all mkdocs: https://github.com/valhalla/valhalla/blob/gh-pages/index.html.

Again, it cannot view anything that's outside of ./docs/docs and CONTRIBUTING.md is in master's root. If we'd like it in the docs HTML version, we'd have to symlink as we did with the root README. We can do that and then put the absolute URL of the docs version, so when someone clicks it on github.com it'll forward to github.io.

[drewda]

@drewda would you mind removing the docs from readthedocs.io once this is merged? Then there won't be any ambiguity with a stale documentation still being live there.

Hi @nilsnolde, I can look into this and see if it's associated with my account.

I'm sure there are sites linking to various pages on valhalla.readthedocs.io, so it would be best to set up redirects. Here's one person's suggestion on how to do so: https://stackoverflow.com/a/69928404

[nilsnolde]

so it would be best to set up redirects

Ah that's a very good point! But man, my motivation getting involved with Sphinx ever again is pretty low 😅

[drewda]

I can't access config on readthedocs. I contacted support and they say that @kevinkreiser is the project owner for valhalla.readthedocs.io

Kevin, can you set up some redirects? Or you can share access with my drewda account and I can try to help.

[nilsnolde]

Ah sorry @drewda , I thought I remembered the account was on your name. Then we’ll figure it out, thanks:)

[drewda]

@nilsnolde np! I think my vague memories of setting this up are probably the formatting work in #1697

[kevinkreiser]

ok ive done the redirect by making a repo and immediately archiving it. now if you try to go to: https://valhalla.readthedocs.io

you will be redirected to: https://valhalla.github.io/valhalla