Rustdoc: reStructuredText vs Markdown

tools and infrastructure
41

I can confirm that Docbook is not better :slight_smile:

42

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.

3 Likes
43

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.

1 Like
44

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.

45

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

46

Can you go into detail why?

47

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

1 Like
48

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.

49

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.)

50

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.

51

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 =)

52

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.

53

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.

1 Like
54

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.

2 Likes
55

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

56

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

57

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

58

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

59

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.

60

@nathantypanski explained earlier, and I have to agree:

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.