Switch page to markdown/mkdocs

[vvolkl]

A test deployment is available under cvmfs.docs.cern.ch. I'm planning to use that as the main URL at some point - cvmfs.readthedocs.io can either mirror or redirect. It shouldn't be a problem either way as readthedocs.io does support mkdocs.

• The biggest issue in keeping the site the same is that mkdocs has no native/simple way to handle different versions of the documentation. There's https://github.com/jimporter/mike but I'm wondering if it isn't actually better to stop building separate versions, and add colored boxes for "New in version... " and "Deprecated in ..." where deemed necessary.

• RST does have a few advantages, in particular the citations have a better syntax. There's a mkdocs-bibtex plugin, but I thought it overkill, plus I couldn't get a full list of references to render correctly. So the citations are basically manually linked to the anchors in the list at the end.

• I've started reorganising the navigation a bit, but it's not complete yet. The links shouldn't be affected as those point to the filenames, and those did not change.
• There were quite a few conversion issues (internal links, tables, ...) and I haven't caught them all. The whole documentation should be checked.
• The .rst files can be removed, and the mkdocs subfolder contents moved up

[DrDaveD]

I'm wondering if it isn't actually better to stop building separate versions, and add colored boxes for "New in version... " and "Deprecated in ..." where deemed necessary.

Please don't do that. Separate versions of the documentation is much preferable. Surely there must be a way to do it using different URLs generated from different git branches, even if it isn't native/simple.

A test deployment is available under https://cvmfs.docs.cern.ch

A quick check of the Appendix -> parameters shows problems there. Probably corresponds to one of the conversion issues.

[vvolkl]

Please don't do that. Separate versions of the documentation is much preferable. Surely there must be a way to do it using different URLs generated from different git branches, even if it isn't native/simple.

Looking again, it is actually fairly simple to do this in mkdocs+mike, it'll put different versions under cvmfs.docs.cern.ch/ as usual, but the version selector seems to be buggy. However, that can be worked around for now with putting the links to the available versions on the front page

[vvolkl]

It seems like mkdocs is no longer maintained and zensical will replace it. Zensical does not support the readthedocs theme or the version switcher at them moment however, so it's probably better to stick with mkdocs for now. Moving from mkdocs to zensical should be easy, once everything is converted to markdown.