[rust-dev] Documentation

Dirkjan Ochtman dirkjan at ochtman.nl
Thu Jan 5 01:39:28 PST 2012


On Wed, Jan 4, 2012 at 20:05, Graydon Hoare <graydon at mozilla.com> wrote:
>  - Generating single-bundle "print-like" documentation artifacts
>   (pdf and epub), including internal-hyperlinks or references
>   when in a non-link rendering ("see page 12").
>
>  - Inline-editing of docs in a browser "by everyone", wiki-style.
>
>  - Viewing in a terminal (man pages, info nodes, plaintext, querying
>   the API docs via a command like "rustdoc -q foo::bar")
>
>  - Having a very-much-like-plaintext editing format.
>
>  - Using "the same" format for API docs and hand-written manual,
>   tutorial, rationale, etc.
>
>  - Having a simple "build" process for the docs that uses as few
>   tools as possible.
>
> I've looked at a variety of tools and to my understanding, few-to-none of
> them do all this.

As a lurker, I suggest you look at Sphinx:

- It can do both HTML and PDF documentation.
- It can generate latex files for further processing.
- It can do API docs (though I'm not sure how much work you'd have to
do to make it grok Rust).
- It uses reST, which makes it easy to write simple things and
possible to do complex things.
- It has an extremely simple build process, although it depends on
Python and Jinja (and possibly Pygments).

Cheers,

Dirkjan


More information about the Rust-dev mailing list