how is the current status? still a markdown-like thing that isn’t markdown?
i’d still like to promote rST. its configurable roles are perfect for documentation.
for example look here. you see the different fonts?
filenames, classes, methods, exceptions, … are all visually distinct and (whenever useful) link to the python stdlib docs or internally. this is all done via roles. refs allow you to just specify the section label and compiling the document, it will insert the section name (and you won’t have to adapt such links to changes)
it’s similarly flexible as LaTeX, but the documents are static and only the roles and directives are defined using a turing complete language, not the whole thing.
While I’m not a rust contributor I did implement Apache CouchDB’s documentation and I learned a few things that might be helpful to you.
Most important is to be clear what you’re trying to achieve. - you’ve got a book, a website, cargo - all of these have Requirements. You will need to compromise, so rank and score these. And make a timely decision.
What functionality is needed?
markdown has limited advanced document functionality
are cross-document references important?
do you need to extend the syntax?
do you need the same format across book, website, crates, stdlib?
Who is expected to write 90% of the docs? Does this tool/process make this really easy for them?
How easy is it for occasional contributors to send in something? Over time this is equally important.
Do you need a native toolchain today for this? I’m sure you’ll end up writing your own eventually in Rust of course!
With CouchDB, the community settled on .rst for 4 reasons IIRC:
we have some top-level python people to fix or implement anything we needed
the functionality was well aligned
the inter-doc links and HTTP/REST-style markup and plugins are a huge win for us
what version something was added or changed is easy
converting from docbook into .rst was do-able as a 1 off task. Enter pandoc, ditto for .md -> .rst also
the generation & publishing toolchain is very easy to install on all platforms incl Windows, Linux, BSD
the people who were going to write the docs could live with the syntax
Note that Sphinx is what we needed, which is not the same as vanilla .rst. This isn’t a big issue, but don’t confuse things.
Finally, people like me who really detest the .rst syntax just wrote the stuff in markdown and used pandoc to convert over before committing #protip.
yeah, i was referring to sphinx as well. nevertheless, rST is what powers it. with plain rST you can use those semantic roles like :math:`\log x^2` or :py:func:`io.BytesIO`, then you need to let your implementation (e.g. sphinx) or extensions you wrote for it (a new role is often like 20 lines in python)
with markdown you don’t have this extensible concept, so you end up inventing syntax extensions that are incompatible with and not seen by other markdown implementations. rST implementations however can e.g. ignore unknown roles or wrap them in <span class="somerole"></span>.
I’m split here. Nothing would stand in the way of making the format in use pluggable (and many other frameworks in other languages do). While I would never drop Markdown, offering other options is sound.
FWIW, I actually think rustdoc should be rewritten from the ground up anyways…
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:
make rustdoc do rST and/or asciidoc as well. both are extensible by default (directives&roles/macros) and therefore adequate
add a Cargo.toml field like doc-format
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)
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.
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.