Agreed regarding ReST.
There are only really two ReST features which I consistently miss in Markdown:
- An intentionally extensible syntax to avoid the need to keep dropping into raw HTML or raw URLs for things like definition lists and apidoc cross-reference markup.
- Footnote markup which automatically hyperlinks in both directions.
The former is what I miss in rustdoc and the latter is why I prefer ReST over Markdown everywhere else. (The latter doesn’t really fit with rustdoc’s templates though)
That said, I’ve been dragging my heels on migrating from the unmaintained, Python 2.x-only ePyDoc when documenting my Python projects because API documentation support in Sphinx is an afterthought. It began as a replacement for the way the CPython 2.x manual used LaTeX and, to this day, its API documentation support hasn’t grown out of that “assume the user has the discipline to maintain good documentation using LaTeX” mindset.
(eg. I see a ton of Sphinx documentation where I have to consult the source code because they neglected to add new auto... directives as the codebase grew or they allowed some of the documentation to fall out of sync in a way rustdoc or a JavaDoc-style tool would never allow. Likewise, ePyDoc will recurse for you so an @todo can’t be accidentally omitted from your index the way Sphinx’s equivalent can if you forget an automodule directive.)
(If I can find the time, my plan is to write and submit a plugin that satisfies my needs for robustness and guaranteed minimum comprehensiveness.)
