Move to mkdocs

[dholbach]

Let's move to mkdocs. The mkdocs-material theme looks nicer, we don't have to use eval_rst tricks and links with anchors work (recommonmark is unmaintained for a while already).

A test build can be seen here: https://test-helm-op.readthedocs.io/

[dholbach]

TODO:

• make GH Action work: Stat liche: no such file or directory (https://github.com/marketplace/actions/link-checker)
• test readthedocs config locally: used https://test-helm-op.readthedocs.io/ instead
• see if our issues (link to anchors in markdown files, etc) are fixed
• adapt our .. note bits
• figure out redirects
• add Flux logo to toolbar

[dholbach]

Looks like I'll need help with the remaining bits (GH action to check links, review content and see if we're happy).

[stefanprodan]

@dholbach can we have the Flux logo displayed in the toolbar?

[dholbach]

Can somebody help me figure out the GH Action? I feel we're getting closer.

[dholbach]

AFAICS all this still needs is:

1. fix the GH Action to check links (important so we can figure out issues)
2. review to make sure nav, look&feel, etc is generally fine for now
3. beautification

[hiddeco]

The mkdocs version from the error does not match the version specified in requirements.txt:

https://github.com/fluxcd/helm-operator/pull/332/files#diff-93bd81aa3a2f0c02728220a6b46fb58dR1

     load_entry_point('mkdocs==0.16.3', 'console_scripts', 'mkdocs')()

This is the version apt installs:

2020-03-16T15:33:33.1807819Z Get:5 http://azure.archive.ubuntu.com/ubuntu bionic/universe amd64 mkdocs all 0.16.3-2 [452 kB]

[stefanprodan]

@dholbach please use this logo https://github.com/fluxcd/flux/blob/master/docs/_files/flux-icon%402x.png

[hiddeco]

Clicking on the logo results in landing on the homepage (fluxcd.io). I think landing on the homepage of the Helm operator documentation would be more user friendly.

[dholbach]

I think we're good for review now. The logo and site_url have been changed and the GH action is working now.

[dholbach]

Current URLs of helm-operator are:

https://docs.fluxcd.io/projects/helm-operator/en/1.0.0-rc9/
https://docs.fluxcd.io/projects/helm-operator/en/1.0.0-rc9/_static/css/theme.css
https://docs.fluxcd.io/projects/helm-operator/en/1.0.0-rc9/_static/pygments.css
https://docs.fluxcd.io/projects/helm-operator/en/1.0.0-rc9/_static/custom.css
https://docs.fluxcd.io/projects/helm-operator/en/1.0.0-rc9/genindex.html
https://docs.fluxcd.io/projects/helm-operator/en/1.0.0-rc9/search.html
https://docs.fluxcd.io/projects/helm-operator/en/1.0.0-rc9/references/index.html
https://docs.fluxcd.io/projects/helm-operator/en/1.0.0-rc9/guides/index.html
https://docs.fluxcd.io/projects/helm-operator/en/1.0.0-rc9/tutorials/index.html
https://docs.fluxcd.io/projects/helm-operator/en/1.0.0-rc9/faq.html
https://docs.fluxcd.io/projects/helm-operator/en/1.0.0-rc9/troubleshooting.html
https://docs.fluxcd.io/projects/helm-operator/en/1.0.0-rc9/references/operator.html
https://docs.fluxcd.io/projects/helm-operator/en/1.0.0-rc9/references/helmrelease-custom-resource.html
https://docs.fluxcd.io/projects/helm-operator/en/1.0.0-rc9/guides/upgrading-to-ga.html
https://docs.fluxcd.io/projects/helm-operator/en/1.0.0-rc9/guides/upgrading-to-beta.html
https://docs.fluxcd.io/projects/helm-operator/en/1.0.0-rc9/tutorials/get-started.html
https://docs.fluxcd.io/projects/helm-operator/en/1.0.0-rc9/tutorials/get-started-kustomize.html
https://docs.fluxcd.io/projects/helm-operator/en/1.0.0-rc9/index.html
https://docs.fluxcd.io/projects/helm-operator/en/1.0.0-rc9/references/
https://docs.fluxcd.io/projects/helm-operator/en/1.0.0-rc9/guides/
https://docs.fluxcd.io/projects/helm-operator/en/1.0.0-rc9/tutorials/

Do we want redirects?

[stefanprodan]

@dholbach the Helm Operator features list has been flattened, can you make it look like in the readme?

[dholbach]

The feature list is the same as in the README, looks like indentation

• a
• b
  • c
• d

doesn't work.

[dholbach]

OK, fixed it now.

[stefanprodan]

I propose we merge this into docs/revamp and make any other adjustments there.

[stefanprodan]

LGTM