To secure longer-term viability of the documentation (and forum), I'd suggest that RST be dropped, and that all documentation is parsed using markdown instead.
As much as I personally prefer the feature-set of RST (due to the clear extension capabilities, as well as the well-defined, parseable structure), clearly it lost the text-format war and thus finding people that are willing to invest in it will grow harder and harder over time. The same applies to tooling that will continue to bitrot, and it's such a bother to remember the differences, this forum included.
To get an idea of how things are developing, here's the google trend: https://trends.google.com/trends/explore?date=all&q=%2Fm%2F0jt0gkj,%2Fm%2F036gl7
Like HTML, the intent of markdown is that it parsing should degrade gracefully - thus any respectable markdown parser will be able to produce at least a decent looking version of the current documentation, as is.
Further, looking towards editors like HackMD, one can see that the amount of tooling to do graphs, figures, math etc is growing in the markdown space - again, this will allow the production of higher quality documentation with less effort and maintenance.
There's never going to be a better time to do this - my hope would be that with increased popularity, more documentation will appear, and the chances of that happening will improve if the barrier to writing high-quality docs is low.
https://hackmd.io/features is a great document to explore what people have managed to do with markdown.
Likewise, it's hard to say bad things about how the rust documentation turns out in practice: https://doc.rust-lang.org/std/result/index.html - it's all markdown-based, checked by the compiler, directly runnable in the browser etc etc.
A few comments and questions from a newby.
I started my project's documentation using markdown with pandoc. I couldn't get any of the TOC options I found to work correctly, so I had to write my own TOC generator.
Then I noticed that nim supported rst with its doc and rst2html commands, so I painfully switched my doc files to that. At least that has a nice TOC generator - once you guess at the required directive. Since my main module html file as produced by doc needs to hyperlink to sections in another hand-written "user guide" file, I had to hack the rst notation and write an html modifier to translate section headings into the mangled labels produced by the nim command rst2html.
So I have these questions:
I will also cast my vote for Markdown, it has won in the rich text space just like git has won in the vcs space...
One could make the current RST parser output markdown once in a one big switch over.
Also to add:
"look at the graphs, Markdown won over RST" is a valid but terrible argument
I agree :). Instead of such statistics, look at how Markdown is getting used probably everywhere in the programming community: GitHub, Gitlab, Reddit, StackOverflow, etc.
Every programmer worth their mettle at least knows how to bold, italicize and write monospace in Markdown.
Not many people will need to be educated on how to write Nim docstrings in Markdown unlike the case right now with the Nim docs and even this forum.
I have no real preference either way, but personally I use Markdown a lot in ruby and also in my local files.
I do not even use markdown directly for ruby, but instead have a template ending with .gen, and a ruby script then expands this with more information when I upload a gem in ruby.
What is really awesome with markdown is that it is so simple, and you can get some simple "styling" too. And you could even use HTML bold tags like <b> too, rather than two stars ** - so it allows for a bit of flexibility.
(HTML) Tables are also quite easy to do in markdown. I like markdown a lot.
I don't mind other forms of documentation but for me personally, Markdown is awesome.
It's not perfect for all cases though. I think some websites may need more control over their content. For example functionality such as "show source code of a method" - that would be pretty difficult with markdown as such (ok ... not really possible right?).
For example, the amount of single backticks denoting code/verbatim (like it is in markdown) instead of double backticks (the RST way) is astounding.
Single backticks are also an RST feature, it's some custom markup that I planned to map to proc arguments but never did.
planned to map to proc arguments
nobody contends that rST is more powerful, syntax- and feature-wise. This thread is about making a pragmatic choice such that Nim development can reuse a well-known and established format that brings 95% of the functionality and instead allowing compiler, tooling and downstream developers focus their attention on things more impactful.