On 2013-06-21, at 03:02 , Brian Anderson wrote: > On 06/20/2013 04:44 PM, Daniel Micay wrote: >> On Thu, Jun 20, 2013 at 7:30 PM, Brian Anderson <[email protected]> >> wrote: >>> Regarding HTML generation, I think we should not lean on pandoc so heavily. >>> rustdoc currently produces a page of markdown at a time to pass to pandoc. >>> This conversion drops a lot of semantic content on the floor. We should >>> instead output proper semantic HTML that is tailored to Rust and only use a >>> markdown renderer to convert small sections of doc comments to HTML. >> We could be making much better use of pandoc since it uses a superset >> of markdown. For example, with an up-to-date pandoc, the function >> signatures and code examples get syntax highlighted. >> >> http://johnmacfarlane.net/pandoc/README.html#pandocs-markdown >> >> Another thing to consider is switching to sphinx and avoiding the pain >> of doing this all ourselves. Converting our markdown to restructured >> text would be pretty trivial. > > I guess if we're going to switch to sphinx now is the time, but I haven't > looked at it. Their web page does make it sound fairly python-centric though.
It was created for Python and is developed in Python (so is the underlying docutils library for processing restructuredtext), so the main community using it is the Python community, but sphinx isn't python specific at all. Most of the markup is generic text things, it bundles non-python domains[0] (code coloration uses pygments so it already does way more than just python) and there is an API for creating new domains, you can find examples of such new domains as part of sphinx-contrib[1]. Switching rust's documentation to sphinx would likely require developing a Rust domain so Sphinx can create all the right cross-references, e.g. :func:`str::each` linking to the right place without requiring further efforts by the documentation author. [0] http://sphinx-doc.org/latest/domains.html#the-c-domain [1] https://bitbucket.org/birkenfeld/sphinx-contrib/src _______________________________________________ Rust-dev mailing list [email protected] https://mail.mozilla.org/listinfo/rust-dev
