Revamp Documentation

[tim-janik]

Our documentation needs to be modernize and reorganized in several places.
Here is how to keep track of the tasks involved, feedback welcome:

• Host docs under https://tim-janik.github.io/anklang/
• Use mkdocs-material for documentation builds.
• Add proper front-page (index.html)
• Integrate C++ API documentation, this needs C++ docs in markdown, possibilities: mkdoxy, moxygen
• Integrate JsDoc documentation about web components and JavaScript utilities
• Rewrite JsDoc Generator + JsDoc pges to work properly with mkdocs-material
• Display runtime help (via F1 key) at the UI, use the markdown-it renderer our UI supports already.
• Add PDF renderings (needs xelatex) to the online docs (TeX doesn't need to be a dep for all builds).
• Add design docs from the Wiki to the docs, like Architecture e.g. via a wiki submodule
• Restructure the documentation to start simple and provide progressively more details, e.g.:
  1. Tutorials
     Lessons/exercise to learn from for beginners that cannot yet ask technical questions.
     Writer decides actions & outcome, exercise turns learners into users. Must be bulletproof, 100% repeatable.
     Does not explain, instead focuses on doing things without options/alternatives.
     Basic concepts.
  2. Guides / How-Tos
     Problem oriented, takes through a series of steps. Provides answer to a meaningful technical question.
     Some flexibility, covers alternatives/variations for slightly different problems users might have. Must be reliable.
     Practical usability over completeness. Needs good sentence title: "Howto create a class-based view"
  3. Reference
     Technical description of the machinery. Code determines structure. Covers lifetimes, fields, interactions.
     Provides information like an encyclopedia. Must be kept in sync with code.
  4. Explanation / Discussion
     Background explanations, historical contexts. Rationales for design decisions. Touches on approach alternatives.

Related: What nobody tells you about documentation A Framework for Better Documentation