Rustdoc: reStructuredText vs Markdown

[flying_sheep]

nah, converting it all isn’t a problem thanks to pandoc. markdown’s functionality is a straight subset of pandoc, and pandoc supports all of markdown so i doubt very strongly that there will be issues.

the world has enough incompatible markdown dialects, it’s time to actually do something right for once. (note that i only mean “not choosing markdown”: other than that there are tremendously many good decisions in the rust exosystem)

i propose the following:

1. make rustdoc do rST and/or asciidoc as well. both are extensible by default (directives&roles/macros) and therefore adequate
2. add a Cargo.toml field like doc-format
3. emit non-markdown (rST or asciidoc) by default. everyone choosing to keep using markdown just has to add the doc-format key.

i can’t let this rest because of how annoyed i am each time i see stuff like this where links to the relevant classes and functions only don’t exist because markdown is used. that’s simply throwing away convenience that we could have had for free (well, once there exists a proper rST or asciidoc lib in rust)

[hauleth]

There is thing in ASCIIDoc named Markdown compatibility http://asciidoctor.org/docs/asciidoc-syntax-quick-reference/#markdown-compatibility. Only thing that would need to be added to it is Markdown link syntax and it would provide compatibility with 99% of the existing documentation.

[djc]

I’m interested in this because I also have a bunch of experience with reStructuredText, and having found Sphinx quite awesome to work with. I’ve now written some Markdown for rustdoc stuff, and I’ve definitely felt that rustdoc/Markdown is very limited in comparison.

I just noted this thread, which seems to has gone on forever, so allow me to get a bit meta: what needs to happen for this issue to make progress? (Or alternatively, maybe something has already happened since this thread was started?) Should there be an RFC about, let’s say, optionally adding reStructuredText and/or ASCIIDoc formats? Or is the RFC process not followed for this type of thing?

The main objections to reStructuredText seem to be “I hate writing reStructuredText”, sometimes substantiated with examples of how it is too strict or has draconian error handling. On the other hand, it seems clear that Markdown (in any of the common varieties) is not extensible enough. So, it does seem like some change is needed.

[lu_zero]

reStructuredText is overly verbose and complex even for simple tasks (e.g. linking urls), markdown with few extension can provide a better experience without extra limitations.

ReadTheDocs already provides some commonmark-docutils bridge so a markdown flavour can be used in sphinx.

[getreu]

On the other hand, it seems clear that Markdown (in any of the common varieties) is not extensible enough. So, it does seem like some change is needed.

I believe Asciidoctor is the best choice to enhance Rust’s markup:

1. Asciidoctor is Markdown compatible and supports its basic syntax.
2. You can write your scientific articles and thesis with Asciidoctor: (example Enhance Embedded System Security With Rust
3. The Asciidoctor tool-chain can render “.pdf”, “html5”, ebook, slides, … with or without docbook.

[lifthrasiir]

Asciidoctor is Markdown compatible and supports its basic syntax.

If my understanding of the compatible syntax is correct, it crucially differs from the link syntax which is an enough problem to be adapted.

[getreu]

With Asciidoctor migration from Markup is made fairly easy as it supports Markup’s basic syntax. Nevertheless for more advanced features you will find more differences. Most important, people can just continue typing the way they are used to. But it is much more: Asciidoc is another way of expressing docbook semantics making it is a powerful as LaTeX.

[getreu]

If my understanding of the compatible syntax3 is correct, it crucially differs from the link syntax which is an enough problem to be adapted.

@lifthrasiir : I forward you Dan Allen’s comment on this:

“Keep in mind it’s possible to add support for the Markdown link syntax using an inline macro extension.”

[dobenour]

AsciiDoctor is GPL which could be a problem. Sphinx is under a BSD license, which is much less likely to be a problem.

[skade]

AsciiDoctors License is MIT: https://github.com/asciidoctor/asciidoctor/blob/master/LICENSE.adoc

[getreu]

Please have a look at a followup in Rustdoc: Asciidoctor vs. Markdown.

[getreu]

Sphinx, a reStructuredText documentation generator, can be easily extended to support Rust

Originally, Sphinx was conceived for a single project, the documentation of the Python language. […] Since Sphinx has become somewhat popular, interest developed in using it for many different purposes: C/C++ projects, JavaScript, […]. The sphinx-contrib repository contains more domains available as extensions; currently Ada, CoffeeScript, Erlang, HTTP, Lasso, MATLAB, PHP, and Ruby domains. Also available are domains for Chapel, Common Lisp, dqn, Go, Jinja, Operation, and Scala.

[ssokolow]

The Python documentation was originally maintained in LaTeX. The fact that Sphinx was designed to replace that shows to this day.

It’s a beautiful tool for writing manuals, but it’s quite inferior when evaluated as a tool for API documentation. For example:

• The autodoc functionality for Python is primitive at best and, if you want anything more automatic than manually maintaining a correspondence between your code and a set of automodule directives, you need to resort to external scripting. (I can’t count the number of Python projects where this forced me to read the source to understand something for lack of proper API docs.)
• If you’re using the “gather TODO notes” functionality and you forget to automodule something, the TODO notes from that module will be silently omitted from the docs.

That’s not to say it couldn’t be used well for Rust… it’d just have to be used as a backend with something new to reliably and helpfully inspect the code and output ReST files for Sphinx to process.

[skade]

Also, it would introduce python to the required toolchain.

[SimonSapin]

Isn’t Python already required to bootstrap the build system?

[skade]

Sure, but without larger dependencies.

[ssokolow]

Also, people other than build system boostrappers use rustdoc.

[getreu]

Linux kernel documentation switched to ReStructuredText

In the end, Sphinx and reStructuredText are emerging as the future of Linux kernel documentation, with far more ambitious goals than the original AsciiDoc support patches ever had. […] “Honestly, in the end I think we could make either tool do what is needed of it. However, my impression after trying to do a document that needs to have nice publishable output with both tools is that Sphinx is easier to work with, simpler to extend, better supported.” In the end, Jonathan’s verdict was to go with Sphinx. The patches have been merged, and the first Sphinx-based documentation will appear in the 4.8 kernel. (Jul. 2016)

[ZelphirKaltstahl]

If Markdown then please use Pandoc Markdown, to at least get basic quoting abilities. With original markdown and many variants one cannot even properly quote (academic standards) a source. It is not possible to do document internal links properly at any place one wants either. Only headings are linkable or external documents. What about sizes of images? Usually not definable in most Markdown variants either.

Markdown is simply way to little power for proper documentation.

That’s why I wrote my academic thesis in ReST instead of Markdown. A proper thesis in Markdown (not Pandoc Markdown) is unthinkable. A documentation for a programming language should at least be on par with academic standards for theses.

That’s my opinion at least.

[konstin]

Markdown is surely insufficient for academic writing. But code documentation shouldn’t be a full-blown academic paper. It should explain the peculiarities of the annotated code while been easy to write and maintain. If required you can still create more complex documentation with an external tool and link to that in the code documentation.