Discuss / document our policy regarding using Markdown in swh-docs
It seems these days the development world is converging on Markdown as its lightweight markup language, more specifically around the GitHub Flavored Markdown variant.
In the context of Software Heritage, this is the markup language that is used by GitLab, our collaborative editor Hedgedoc, amongst probably other minor tools.
Software Heritage documentation is written using Sphinx. While Sphinx has many interesting features, it was designed around reStructuredText, the markup language designed for the CPython project in the early '00s.
reStructuredText has several quirks, like not being able to do nested markup, but these days, its main problem is simple that it is not Markdown. It means that any documentation initially written on Hedgedoc or GitLab needs a conversion. Both are close enough that going from writing in one language to the other leads to mistakes. There is already several instance where documents had to be fixed because they were initially written in Markdown, for example eb0c45b5, f75b1db1, 3bc9848d.
While this could look like bikeshedding, we should evaluate how much this discrepancy is detrimental to having better documentation, decide and document a policy.
Support for using Markdown with Sphinx has become much better with the development of the MyST language and parser which started in 2020. It is fully supported by the most visible Sphinx documentation hosting platform Read The Docs. The documentation for the sphinx-design extension shows Markdown syntax first. MyST can also be nicely previewed in VSCode, as it benefits from the builtin Markdown previewer. The equivalent reStructuredText extension has been quite fragile so far.
Options
Possible policies for the future:
- Status quo (according to my understanding): anyone do as they please when writing a new document.
- Decide we prefer reStructuredText. Convert the existing documentation from Markdown to reStructuredText for coherence.
- Allow some part of the documentation to be written in Markdown. Both languages are equally preferred.
- Decide we prefer Markdown but only use it for newly written documentation.
- Decide we prefer Markdown. Convert existing documentation on refactoring or major updates happen.
- Migrate all the existing documentation to Markdown. (See guide from Read The Docs.
If at some point we would like to fully migrate away from reStructuredText, the very recently released autodoc2 supports MyST docstrings.
History
Back in 2017, support was enabled for Markdown files. This was actually in the ery early days of swh-docs
.
In 2020, recommonmark was replaced by MyST parser.
As far as I could see, the first and only part of the doc written in Markdown is issue-debugging-monitoring.md that was initially added in 2021.