Documentation structure: use readthedocs

[sanjayankur31]

I wanted so start putting up the templates here for review. Since the idea is for the information here to be used for community members to review their tools and learn about the current suggested software development practices, it'll be good to also document the various checks that the templates include.

So, I was thinking of using readthedocs for this:

• different review sections (one for each programming language, for example) will have different documentation pages
• each documentation page will provide a link to a "review template" (or it can include it as pre-formatted text at the end)
• each documentation page will explain the rationale behind each check in the template

Users will then be able to copy the review templates and open issues at the projects they're reviewing.

Does this workflow sound OK? Can it be made easier perhaps?

[malinINCF]

This sounds good to me.

[joewgraham]

Works for me!

[sanjayankur31]

Great, thanks. I'll wait a few more days and start setting rtd and the initial bits up. I'll open PRs so that people can review the guidelines before they get merged.

[mstimberg]

General workflow sounds good from my side as well. A general idea/suggestion: I sometimes struggle a bit with the continuous switch between Markdown and ReStructuredText, how about using MyST to write the docs with Sphinx + Markdown? I've never tried it, but I feel that nowadays many people are familiar with Markdown (jupyter notebooks, github, discourse, ...), and ReStructuredText is not much used outside of Python documentation.

[sanjayankur31]

That sounds good. I hadn't run into MyST yet. I'll check it out and set it up too. ( I'd included the "recommonmark" extension which allows one to write with Markdown too: https://www.sphinx-doc.org/en/master/usage/markdown.html )

[mstimberg]

Ah, I hadn't seen that you included recommonmark already. From what I understand, MyST is more principled replacement of RST, whereas recommonmark is Markdown + embedded RST. But I never used either of them, so I cannot strongly advocate for using one or the other.

[sanjayankur31]

I'll look into them. I thought recommonmark just allowed one to write in md.

Additional note: I updated the repo name to "SoftwareDevelopmentGuidelines" so it's clear that the information here is a general resource for anyone to refer to.

[sanjayankur31]

I've worked on a few projects with jupyter-book now, and that looks very good. It also allows writing in MyST etc., so I'll switch to that.