Move doc to GitHub about cmf

[philippkraft]

(w2)

Blogs

https://vincent.bernat.im/en/blog/2011-migrating-to-github

Tools

http://markitdown.medusis.com/
https://pandoc.org

Code

https://gist.github.com/somebox/619537

[philippkraft]

(a2)

Done and available under https://philippkraft.github.io/cmf

Need to create a nice landing page for philippkraft.github.io

[philippkraft]

(w1) Solved

(w2) still problematic

(w3) major blocker due to: github/markup#274

That means, no formulas possible in wiki

[philippkraft]

Alternatives for (w3)

Option 1: Use doxygen for tutorial and API

Tutorials are translated to markdown and saved as .dox files. Doxygen compiles the tutorial together with the API documentation. The result is copied to docs and available under http://github.io/philippkraft/cmf

Pro & Contra:

• Pro: Simple (automatic) linking between tutorial and API
• Con: Ugly / Clumsy Doxygen style everywhere

Option 2: Use another compiler eg. Sphinx / Docutil /mkdocs for the tutorial

Tutorials are translated to rst (Sphinx, Docutil) or also markdown (mkdocs). The API documentation from doxygen is compiled into docs/api and the tutorial is compiled into docs/tutorial. A new docs/index.html page will navigate to the tutorials resp. API

Pro & Contra:

• Pro: Better styles available, esp. Sphinx style is common for Python programs
• Con: Don't know how to link to API from tutorial

Option 3: Use Jupyter notebooks in the GitHub wiki

See this gist. Jupyter Notebooks might even provide much more functionality for a tutorial

Pro & Contra:

• Pro: No extra compilation step necessary
• Pro: Provides functionality for a tutorial
• Con: More difficult to write (see the source code of the gist).
• Con: Needs more time to learn
• Con: Don't know how to link to API from tutorial

[philippkraft]

Setteled for Option 1. Works super.