guide
guide copied to clipboard
NLeSC
Update Python chapter on preferred markup language
We have switched (back) from ReStructuredText (rst) to MarkDown as the default documentation format in the NLeSC Python template. This has historically been a slightly controversial choice in the Python ecosystem, where rst has been the norm (hence the original switch to rst in the template). Nowadays, MarkDown seems well supported as well. Since it is generally seen as easier to use, and we want to lower the barrier to people documenting their code as much as possible, it seems we should start recommending people to use MarkDown in the guide as well. We should probably also briefly motivate our choice there, for which the previous sentences could suffice. Further supportive material can be found in discussions via mail and in Teams chat of April 13th 2021. To give the full picture, the downsides should also be mentioned, so people can make their own well informed choice. Apart from the Python ecosystem dominance of rst mentioned already, rst may also scale better to larger documentation projects, like when writing large manuals. Furthermore, as highlighted by @merijn, MarkDown is a PITA to machine-read, whereas rst is not.
We have switched (back) from ReStructuredText (rst) to MarkDown as the default documentation format in the NLeSC Python template.
The documentation in the template still seems to use .rst: https://github.com/NLeSC/python-template/blob/main/%7B%7Bcookiecutter.directory_name%7D%7D/docs/index.rst
Is this just about the package description on PyPI then? Or about the entire documentation?
For me, the reason to use markdown for the description of the package on PyPI is that you can conveniently re-use README.md that all GitHub projects have (by default?).
Apparently these changes are planned in the Python template, not implemented yet: https://github.com/NLeSC/python-template/issues/299.
Ah I see, my bad. Still up for discussion then, or decided already? Can someone from the generalization team pitch in? @fdiblen
This looks like an interesting guide to link to? https://learn.scientific-python.org/development/ ?
