Rustdoc: reStructuredText vs Markdown

[steveklabnik]

I can confirm that Docbook is not better

[mkpankov]

As much as I’m used to Markdown and as convenient it’s to write, I think using something more standard, powerful and extensible is a better long-term solution. ASCIIDoc looks very cool with it’s attribute syntax. Besides, if one is able to learn Rust I don’t think learning yet another (better!) markup language would be a problem for them.

[tupshin]

Huge +1 to asciidoc. The fact that you can write a legitimate full-length book in it is hugely promising. https://atlas.oreilly.com/ is all based around asciidoc.

[sinistersnare]

I think it would be nice to have a Markup trait that Rustdoc uses, defaulting to Markdown.

That way you can write any markup you want.

If there is a reStructuredText rust library, people could use that, there is the Hoedown bindings, or any other language.

[bjz]

Looks like AsciiDoc also supports latex math! http://asciidoc.org/userguide.html#X78

[vks]

… but I really, really, really hate writing ReST. .

Can you go into detail why?

[vks]

Huge +1 to asciidoc. The fact that you can write a legitimate full-length book in it is hugely promising. https://atlas.oreilly.com/ is all based around asciidoc.

I know people who wrote their thesis or book in ReST.

[Gankro]

This seems like a non sequitur. Plenty of people write theses in LaTeX; that doesn’t make it appropriate for a programming language’s documentation format.

[vks]

Well, I think the point is that it is possible to use ReST/asciidoc to write highly structured documents, which is not possible in Markdown. Currently Rust’s documentation seems to suffer by this lack of structure.

(Python actually used LaTeX for documentation! If I remember correctly, the main problem was that it did not generate nice html. Hence they switched to ReST and created sphinx.)

[hgrecco]

Being a user of ReST and Markdown, my summary would be. Markdown is great to write small and simple documents. But ReST is much better when you want more complex, richer docs.

[lu_zero]

I stated to experiment bridging docutis (and thus sphinx) with commonmark-py to see exactly how the discussed extensions to support special-meaning blocks would work for this exact use case and see what’s missing.

I guess more feedback on the forum would be welcome and if somebody feels well versed in hacking python help completing the prototype is welcomed as well =)

[estin]

Sphinx have a documenter abstraction - grab docstrings from source and build signatures, links etc.

Now sphinx have documenter for python only, but sphinx can be extended for new documenters.

I have extension - autoanysrc for sphinx for documenting any sources in native way for sphinx.

It is easy build documenter for rust. Sorry for my poor English.

[sinistersnare]

Is it impossible to not make it pluggable?

we can have an interface for it, so rustdoc can use multiple backends for doc generation… The default could be markdown, as it is now…hmmm idk

$ cargo doc --backend=markdown
$ cargo doc --backend=asciidoc
$ cargo doc --backend=ReST

I would love to work on that…damn school precluding my ability to look into this.

[DanielKeep]

Would be nicer to have it in the doc itself, with localised overrides.

#![doc_markup="asciidoc"]

#[dock_markup="rest"]
pub mod room {
    /**% markup: markdown
    Oh, hey
    */
    fn mark() {}
}

That way you can cargo doc without needing switches.

[sinistersnare]

What a nice idea Wonder how the finding of external markup compilers would work. maybe just search the path for an executable of that name? Idk

[tupshin]

How about the name referencing a crates.io crate with the necessary functionality?

[DanielFath]

It seems like what we need is a Rust fork of pandoc.

[sinistersnare]

The rust team probably wants to keep rustdoc blind of anything crates.io or cargo related.

[sinistersnare]

I think the problem is the functionality of getting rustdoc to allow multiple types of markup, not necessarily the availability of such types of markup.

[wackywendell]

… but I really, really, really hate writing ReST. .

Can you go into detail why?

@nathantypanski explained earlier, and I have to agree:

It’s hard to write.

• ReST is very picky and structured, unlike Markdown, and will break things in weird ways if you don’t use three spaces in exactly the right place.
• Directives can behave strange and still often leave me unsure why my link isn’t working.
• Title syntax is more annoying than Markdown (and more picky; title underlines only - and they have to be the same exact length as the phrase above them).

To add my own:

• Most implementations of ReST I’ve seen do a very bad job of telling you where and why your ReST is not working. Mostly, they just give you some semi-broken output.

I’m also going to say that AsciiDoc is looking pretty good to me, too - it looks much less finicky than ReST, except perhaps for tables (which seem to be hard in any markup language), and it also has a large set of the features we’re looking for, unlike Markdown.

I also just read the Wikipedia article on it, and apparently “Most of the Git documentation is written in AsciiDoc”, not just Pro Git - so while it may not be as widespread as Markdown or ReST, but it does have some precedent.

Either way, it seems like whether or not we stick with Markdown for the foreseeable future, we may want to leave the door open for other options later on.