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