Investigate moving invenio.rtfd.io to MkDocs

[diegodelemos]

• Document what are the implications
  • Are there blockers?
  • What problems are we getting in exchange?
  • Do we have to put more work than needed to have the same content displayed? (i.e. imagine we need Sphinx autodoc and MkDocs doesn't provide it, we are not going to reimplement it)

If it makes sense to make the migration:

• Move docs
• Change look and feel to inveniosoftware's Framework style (https://inveniordm.docs.cern.ch/, https://invenioils.docs.cern.ch/)
• Manage redirects and broken links

[topless]

MkDocs for invenio

Sphinx	MkDocs
✔️	✔️	autodoc support
✔️	✔️	table of contents
✔️	✔️	theme support
✔️	✔️	extension support
➖	✔️	search (preview)
➖	✔️	shortcuts for navigation

for the comparison invenio (sphinx), invenio-rdm, invenio-ils and reana (mkdocs) docs were used.

pros

• consistent look and feel for invenio ecosystem
• replacing rst format with widely used md
• easier customization
• automatic translation rst -> md

cons

• will require some work for the migration
• possibly will need to re-organize the docs a bit

more

• introduce markdown lint for even higher quality
• dead link validation

observations

1. As far as I can tell there is no feature from Sphinx that does not already exist in MkDocs. There are no obvious blockers.
2. TOC of contents might need some extra work to be migrated automatically.
3. Possibly static files i.e. images might have to be moved and corrected manually.
4. We will have to decide how we will organize the content in the new layout & navigation.