Tutorials on Readthedocs or on MATRX-software.com

[thaije]

We have two types of documentation:

• Full documentation of every function within MATRX, with required arguments etc. This documentation is automatically generated with SPHINX, and put on matrxs.readthedocs.io.
• Tutorials and other manually created guides. E.g. the installation guide.

The question is if we want to create and show the tutorials and guides also on matrxs.readthedocs.io, or expand our normal website and add them there. The differences are:

on readthedocs

Pros:

• Aside from creating the tutorial itself, including a new tutorial page on the readthedocs website is easy.
• Makes sense to put it together with all other documentation.
• Easy making links to functions in the code (in theory).
• Easy for unknowns to contribute by creating tutorials: people can create new tutorials and request a merge-request, as such adding it to our readthedocs.

Cons:

• Have to write tutorials in rst format, which is a type of non-intuitive markdown.
• RST is horrible, so less likely for community to build tutorials which can be added to our readthedocs.

Examples:

• scikit-learn.

on our own website

Pros:

• Easy to add new pages in a website with a backend, such as Wordpress or something similar.
• Ability for people to post comments on tutorials
• More freedom in styling the tutorials or adding extra content.
• Can pass people a low-permission account, that can only add tutorial pages (requiring approval before being posted).

Cons:

• Have to expand our one-pager website to use something such as Wordpress.
• Linking to code functions (on matrxs.readthedocs.io) has to be done manually, and is thus more tedious.
• Adding community tutorials to our site requires us to manually create a low-permission user account, or manually copy paste the tutorial (with permission).

Examples:

• OpenAI Gym, although OpenAI seems to user their normal website only.

[thaije]

Verdict after meeting with MATRX team on 13-2-2020: Keep the reference documentation on readthedocs.io, and port to docs.matrx-software.com eventually. Put the tutorials on matrx-software.com.