In many cases we need some equivalence of structure tags in rST, most of that
can be supported via embedding rST(because markdown was not designed for
related constructs). Then it is a bit like inlining asm in another language.
The general new constructions in myST dialect might need some time
> Would either md or rST allow for cross-references between the python API
> documentation and the C++ documentation? I think that would be the biggest
> feature for me, since it would give a clear way to indicate which functions
> are intended to only be wrappers.
they both do via references
@tqchen thanks for the context. I agree that it may not be worth it if you
still have to learn restructuredtext to write a single document. with that
said, I do think that MyST-Parser seems to be an improvement over recommonmark.
There is also some [more
context](https://github.com/readthedoc
I think I'd lean towards markdown for consistency with other services, but
that's only if all other features were equal. Markdown would be nicer for
reviewing, since it can be viewed from github in the browser, but the I think
cross-references are the more important feature.
Would either md
Thanks @areusch . To provide a bit of background, our document was initially
built with Sphinx markdown parser(recommonmark) that allowed a mix of rst and
md. We also made several contributions to recommonmark to structify certain
markdown elements.
As we start to write more structured compon
