Rustdoc: reStructuredText vs Markdown

tools and infrastructure
21

In other news, hoedown just merged in mathjax support! https://github.com/hoedown/hoedown/pull/114

So that’s two points for markdown this morning.

22

This appears to be a topic we would be interested in tracking, re: standardized extensibility. http://talk.standardmarkdown.com/t/add-plugin-syntax-to-the-spec/122

1 Like
23

Political issues aside (“Standard Markdown” has acquired a bit of a debate surrounding it) I really quite like their source code.

It’s quite readable, and if you’re correct in that they’ve designed the standard to be easy to implement, I think this is a good thing.

24

I’ve been trying to force myself to read generated docs instead of library sources and it’s always really annoying when identifiers aren’t linked to their definition. I sympathize with it being much easier to just write `blah()` than making sure the name resolves to its definition at make doc time but imo non-pervasively-hyperlinked docs aren’t good enough and I don’t think [a non-unrecognizably extended variant of] markdown can address that.

25

How can Markdown not address hyperlinking?

Say we define our own syntax for referencing a Rust function. It can even rip off ReST, without the rest of ReStructured Text’s horrible syntax. For example, we could use code blocks to dictate which part of a fully-qualified item gets hyperlinked:

The parser would have to look for :rs:, followed by a path name that uniquely qualifies an item.

If you’re searching for this post-markdown-compile, then you can look only for “plaintext” that begins with :rs: and ends with ::, followed immediately (no whitespace) by an inline code block. Then you test against the above rule. If it passes, you insert a link.

This is made possible because, without changes, those markdown strings render as, e.g., :rs:option::Option::is_some().

Surely this wouldn’t address every edge case, but it’s a reasonable start and doesn’t blast Markdown into the realm of “completely unrecognizable.” Additionally, the likelihood that the strings I mentioned would turn up in normal usage of Markdown is extremely low.

26

@benh: I was thinking about similar issues, but from a different point of view: Currently links to documentation of other parts seems to be mostly done with links to other documentation pages, which kind of hard-codes the layout of the generated documentation, and makes it hard to extract links for other documentation browsers (command line interfaces, desktop documentation browsers, or extracting related resources).

My idea would’ve been to have a rust scheme for links, like rust://crate/mod/type.method or rust:/mod/type.method for local references. Though the crate part is a bit hard to do if you want to reference non-dependencies, since you’d have to resolve it somehow.

2 Likes
27

I like this syntax better than my suggestion, since it doesn’t require custom parsing logic. I suppose I’ve been writing too much ReST lately for my own good.

28

My idea would've been to have a rust scheme for links, like rust://crate/mod/type.method or rust:/mod/type.method for local references.

I like this idea, it works well with the constraints of markdown.

Though the crate part is a bit hard to do if you want to reference non-dependencies, since you'd have to resolve it somehow.

The way that Python handles this is with intersphinx, a sphinx extension which just helps map domains to indexes. Since rustdoc is already generating indexes for search it should be straightforward to expose the index file on doc sites. Then it's just a matter of pointing to it in Cargo.toml or Rustdoc.toml or somewhere.

29

That is a very nice solution, I didn't even think of that. That would make it possible for software to resolve/traverse a full graph of linked code. Which would also be nice since you can have tools to download crates including non-dependency related ones when you're planning to be offline for a bit. I can also imagine use-cases for search interfaces.

30

Optimistically, we could also just do regular name resolution on path-looking code spans, and hyperlink the result if there is one. At least for actual code blocks of the sort that is tested by make check, that ought to help…

31

It’s also slow unfortunately.

32

Common Markdown still lacks a formal grammar, so there’s room for ambiguity in the spec. http://talk.standardmarkdown.com/t/commonmark-formal-grammar/46 discusses this and attempts to define a grammar.

33

Pro Git moved from markdown to asciidoc : https://news.ycombinator.com/item?id=8509062

I’m increasingly thinking that ASCIIDoc might be the right move.

2 Likes
34

ASCIIDoc looks really capable (cheatsheet). :+1:

1 Like
35

Anyone willing to provide an executive summary of strengths/weaknesses vs reStructuredText or just extending markdown? How does it address the usecases in this thread?

36

I’m definitely in favour of simply using markdown as is and extending it when needed. It’s universally used throughout the programming communities (online and offline) and it’s just a natural way to enhance standard text. Because markdown is so heavily used with Github, Stackoverflow, Discourse, etc… it’ll be super friendly to who ever learns Rust.

1 Like
37

I think that staying with Markdown seems like a good idea. One of my favourite things about Markdown is the way its basic elements resemble normal ASCII text, and it doesn’t obviously show that it is actually a markup language, making it easy to read even when it’s not rendered. That means that reading docs from the source code also works well and seems natural, rather than everything being cluttered with line noise like :rs: that obscures the real documentation.

I think that if we’re missing any kind of functionality from Markdown, we should just extend it: something like `foo::[bar::baz]` (or even just `foo::bar::baz`) for links to items, for example, would be fine in my opinon. I see little reason to adhere precisely to a standard: while it makes sense to follow a standard so that it is predictable, I doubt that adding anything to Markdown would cause much trouble.

1 Like
38

I like ASCIIDoc too. MarkDown don't have a uniform standard, too many dialects, such as John Gruber's Markdown and Jeff Atwood's Common Markdown. ASCIIDoc is more powerful than Markdown as a markup language, with rich built-in features (Syntax highlight, table, include files, document header, compatible Markdown), and the Asciidortor is easy to use as a toolchain. O'Reilly Atlas publishing platform already support ASCIIDoc.

About 《Pro Git 2》: Living the Future of Technical Writing

1 Like
39

I don’t think alternatives have enough benefits to outweigh the sheer momentum of Markdown in docs at this point. We should probably just be investigating how to add this functionality on top of “vanilla” markdown. Possibly this will fall out of some CommonMark extension efforts.

40

Agreed.

Markdown is nice and simple. The drawback is, it is too simple. Sometimes I think that even docbook would be better than MD…