Sphynx or MkDocs for documentation?

[RobinL]

see e.g. https://news.ycombinator.com/item?id=17717295

Leaning on side of Sphynx with docs written in markdown

[mamonu]

sphinx in my opinion too.

[mamonu]

ok have done a first draft. will create a pull request

[mamonu]

in order to do this i consulted the 3 following docs

https://www.sphinx-doc.org/en/master/index.html https://www.sphinx-doc.org/en/master/man/sphinx-apidoc.html

with the help of An idiot’s guide to Python documentation with Sphinx and ReadTheDocs

https://samnicholls.net/2016/06/15/how-to-sphinx-readthedocs/

TLDR the file to edit for configuring sphinx is conf.py in the docs\source directory

[mamonu]

added also !docs/* on .gitignore as otherwise the build part of the docs is not saved because of a previous build/ statement

[mamonu]

integrating markdown a bit better based on:

http://www.sphinx-doc.org/en/master/usage/markdown.html

and

https://stackoverflow.com/questions/2471804/using-sphinx-with-markdown-instead-of-rst

[mamonu]

This is a nice way to think about the documentation of sparklink: with autodoc the API will always be documented but it will be the reference part and we will need to think about the rest

[RobinL]

Closed by #22