move to mkdocs

[dholbach]

First cut at moving docs over to mkdocs for flux too (follow up from fluxcd/helm-operator#332)

[dholbach]

To review, run:

pip3 install -r docs/requirements.txt
mkdocs serve

[dholbach]

The navbar on the left is something we can still tweak, and we might want to take a look at the currently quite empty index.md files.

[stefanprodan]

Can we have a preview link like you did for helm-op?

[dholbach]

Can do, it'll be manual though, as I don't think I can set up webhooks easily.

[dholbach]

https://test-flux.readthedocs.io/en/latest/

[dholbach]

The landing page (docs/index.md) looks very boring right now as there's no "toctree: depth 2" kind of thing - maybe there's some plugin to do this? Maybe we should symlink the top-level README.md?

[stefanprodan]

@dholbach I think the index should contain the diagram and the feature list (like we did for helm-op). I'll make the feature list, please add the diagram for now.

[dholbach]

I think we're mostly good to go now.

[dholbach]

Current URLs for latest are:

https://docs.fluxcd.io/en/latest/
https://docs.fluxcd.io/en/latest/_static/css/theme.css
https://docs.fluxcd.io/en/latest/_static/pygments.css
https://docs.fluxcd.io/en/latest/_static/custom.css
https://docs.fluxcd.io/en/latest/genindex.html
https://docs.fluxcd.io/en/latest/search.html
https://docs.fluxcd.io/en/latest/introduction.html
https://docs.fluxcd.io/en/latest/requirements.html
https://docs.fluxcd.io/en/latest/get-started/index.html
https://docs.fluxcd.io/en/latest/references/index.html
https://docs.fluxcd.io/en/latest/guides/index.html
https://docs.fluxcd.io/en/latest/tutorials/index.html
https://docs.fluxcd.io/en/latest/faq.html
https://docs.fluxcd.io/en/latest/troubleshooting.html
https://docs.fluxcd.io/en/latest/contributing/index.html
https://docs.fluxcd.io/en/latest/references/blueprint.html
https://docs.fluxcd.io/en/latest/references/daemon.html
https://docs.fluxcd.io/en/latest/references/fluxctl.html
https://docs.fluxcd.io/en/latest/references/fluxyaml-config-files.html
https://docs.fluxcd.io/en/latest/references/garbagecollection.html
https://docs.fluxcd.io/en/latest/references/git-gpg.html
https://docs.fluxcd.io/en/latest/references/automated-image-update.html
https://docs.fluxcd.io/en/latest/references/helm-operator-integration.html
https://docs.fluxcd.io/en/latest/references/monitoring.html
https://docs.fluxcd.io/en/latest/guides/provide-own-ssh-key.html
https://docs.fluxcd.io/en/latest/guides/use-git-https.html
https://docs.fluxcd.io/en/latest/guides/use-private-git-host.html
https://docs.fluxcd.io/en/latest/guides/upgrading-to-1.0.html
https://docs.fluxcd.io/en/latest/tutorials/get-started.html
https://docs.fluxcd.io/en/latest/tutorials/get-started-helm.html
https://docs.fluxcd.io/en/latest/tutorials/get-started-kustomize.html
https://docs.fluxcd.io/en/latest/tutorials/driving-flux.html
https://docs.fluxcd.io/en/latest/contributing/get-started-developing.html
https://docs.fluxcd.io/en/latest/contributing/building.html
https://docs.fluxcd.io/en/latest/index.html

I'm wondering if we should add redirects for them all?

[hiddeco]

To prevent the projects vs organization mix-up:

diff --git a/mkdocs.yml b/mkdocs.yml
index fc3b535d..640d52a6 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -1,6 +1,6 @@
-site_name: Flux CD
+site_name: Flux
 # site_description:
-site_author: Flux CD Project
+site_author: Flux contributors
 site_url: https://docs.fluxcd.io/

 # Repository

Roboto Mono is already the default font for code, I also think a slightly smaller navigation title and logo look better:

diff --git a/docs/_static/custom.css b/docs/_static/custom.css
index fa1bff16..0c7edb7a 100644
--- a/docs/_static/custom.css
+++ b/docs/_static/custom.css
@@ -1,29 +1,24 @@
 @import url("https://fonts.googleapis.com/css?family=Montserrat&display=swap");
-@import url("https://fonts.googleapis.com/css?family=Roboto+Mono&display=swap");

 body {
   font-family: "Montserrat", sans-serif;
 }

-.rst-content pre.literal-block, .rst-content div[class^="highlight"] pre, .rst-content .linenodiv pre {
-  font-family: "Roboto Mono", monospace;
-}
-
-code {
-  font-family: "Roboto Mono", monospace;
-}
-
 .md-logo {
-    width: 54px;
-    height: 54px;
+    width: 40px;
+    height: 40px;
     padding-bottom: 2px;
     padding-top: 2px;
 }
 .md-logo img {
-    width: 44px;
-    height: 44px;
+    width: 40px;
+    height: 40px;
 }

-.md-header,.md-footer-nav {
+.md-header, .md-footer-nav {
     background-image: linear-gradient(45deg, rgb(0, 150, 225) 0%, rgb(27, 141, 226) 24%, rgb(42, 125, 227) 53%, rgb(53, 112, 227) 78%, rgb(53, 112, 227) 100%);
 }
+
+.md-header-nav__title {
+    font-size: .85rem;
+}

[dholbach]

nice one, thanks @hiddeco

[dholbach]

Apparently we can't use mkdocs-redirects for the above.

WARNING -  redirects plugin: 'introduction.html' is not a valid markdown file! 

[dholbach]

So yeah, for now this is all we can do. Please review and let me know when you want to land this. It'll require changing one setting from "sphinx" to "mkdocs" in the RTD UI.

[dholbach]

Do we want something like this https://github.com/weaveworks/wksctl/pull/153/files#diff-b67911656ef5d18c4ae36cb6741b7965L150-R152? The wksctl team wanted it.

[hiddeco]

Awesome work, thanks a bunch @dholbach ⭐