Rustdoc: reStructuredText vs Markdown


#82

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.


#83

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.


#84

Also, it would introduce python to the required toolchain.


#85

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


#86

Sure, but without larger dependencies.


#87

Also, people other than build system boostrappers use rustdoc.


#88

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)


#89

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.


#90

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.


#91

Agreed regarding ReST.

There are only really two ReST features which I consistently miss in Markdown:

  • An intentionally extensible syntax to avoid the need to keep dropping into raw HTML or raw URLs for things like definition lists and apidoc cross-reference markup.
  • Footnote markup which automatically hyperlinks in both directions.

The former is what I miss in rustdoc and the latter is why I prefer ReST over Markdown everywhere else. (The latter doesn’t really fit with rustdoc’s templates though)

That said, I’ve been dragging my heels on migrating from the unmaintained, Python 2.x-only ePyDoc when documenting my Python projects because API documentation support in Sphinx is an afterthought. It began as a replacement for the way the CPython 2.x manual used LaTeX and, to this day, its API documentation support hasn’t grown out of that “assume the user has the discipline to maintain good documentation using LaTeX” mindset.

(eg. I see a ton of Sphinx documentation where I have to consult the source code because they neglected to add new auto... directives as the codebase grew or they allowed some of the documentation to fall out of sync in a way rustdoc or a JavaDoc-style tool would never allow. Likewise, ePyDoc will recurse for you so an @todo can’t be accidentally omitted from your index the way Sphinx’s equivalent can if you forget an automodule directive.)

(If I can find the time, my plan is to write and submit a plugin that satisfies my needs for robustness and guaranteed minimum comprehensiveness.)


#92

That’s exactly why I wrote pdoc: https://github.com/BurntSushi/pdoc — Although I’ve not done a great job maintaining it.