Switch to MkDocs

[MatthewCroughan]

Things we can't do without great difficulty in Sphinx:

• Insert device related info on a page (with conditionals) Implement substitutions for smarter docs  #164 (comment)

• E.g: If this page has the "imx8mm" tag, then insert a link in a note at the bottom
  of page

• Collaborate easily as a team (All written in markdown)

  • Well thought out and separated functionality for
    • Writers (Us)
    • Designers (Milo)
    • Contributors (Anyone)
      This is demonstrated here

Who uses it?

• GlusterFS
• Traefik
• Flox

Benefits

• Most of the Sphinx plugins we are using are native functionality in MkDocs.

• No cruft. Sphinx was developed to document Python code, thus has a lot of
  superfluous functionality that often gets in the way of the way we want to
  document normal things. This is primarily why RST is used.

  • Cares about indendation (Makes development slower and expression of spaces and newlines harder due to the amount of technicalities with indentation)
  • Too strict (Makes CI really hard due to false positive errors that cannot easily be ignored or turned off)

• Better SEO (via tags and author details, etc.) SEO enhancements / requests #137

Notes

• Small but determined community, available in the #mkdocs IRC

  • Usually pretty responsive
  • Issues are fixed in days

• Written in Python, just like Sphinx.

• Provides Jinja templating with conditionals as native functionality

  • Implement substitutions for smarter docs  #164 (comment)

• Is just plain better than Sphinx for what we're doing

Yocto developers

Wrote their own incomplete pre-processor just to replace ampersand &variable's

These variables are global, meaning we still cannot make smart pages and
templates that fill out depending on local variables like the architecture the
file says it represents - using markdown tags/labels for example: (%arm64,
%riscv64, %etc).

• Nicolas Dechesne had to write these pre-processors in Python
  Commit1
  Commit2

[MatthewCroughan]

From time to time, we struggle with redirects. Redirects are made manageable in MkDocs without modifying the webserver configuration via this plugin https://pypi.org/project/mkdocs-redirects/

[kprosise]

Reasoning copied to confluence as arguments in support of MkDocs.Closing issue.