I've been experimenting with using Sphinx [1] for GCC's documentation. You can see an HTML sample of GCC docs built with Sphinx here: https://dmalcolm.fedorapeople.org/gcc/2015-08-31/rst-experiment/gcc.html (it's a work-in-progress; i.e. there are bugs).
Compare with: https://gcc.gnu.org/onlinedocs/gcc/index.html In particular, note how options get stable, clickable URLs: https://dmalcolm.fedorapeople.org/gcc/2015-08-31/rst-experiment/option-summary.html as compared to: https://gcc.gnu.org/onlinedocs/gcc/Option-Summary.html#Option-Summary Example of an option URL, for "-ftree-loop-if-convert-stores" (also showing syntax-highlighted example code): https://dmalcolm.fedorapeople.org/gcc/2015-08-31/rst-experiment/options-that-control-optimization.html#cmdoption-ftree-loop-if-convert-stores as compared to: https://gcc.gnu.org/onlinedocs/gcc/Optimize-Options.html#index-ftree-loop-if-convert-1054 (where I had to use via "View Source" to find that URL, and what's up with that "-1054" wart? note also that the number can change, making the URL unstable) Example of a stable URL for "What does -O2 do?": https://dmalcolm.fedorapeople.org/gcc/2015-08-31/rst-experiment/options-that-control-optimization.html#cmdoption-O2 ...etc Every HTML page also gets a "Show Source" link, showing the input markup. Sphinx is a modern, well-maintained documentation toolchain, implemented in Python. The input format is an easy minimal-markup "semantic" format; the output is high-quality HTML, with PDF and texinfo supported amongst other output formats. It was created for documenting the Python programming language, and is in use by many FLOSS projects for their docs, including e.g. LLVM (http://llvm.org/docs/). See also: http://sphinx-doc.org/examples.html (though this list is far from complete). It's BSD-licensed. We are currently using Sphinx for libgccjit: https://gcc.gnu.org/onlinedocs/jit/index.html and, I believe, for Ada: https://docs.adacore.com/gnat_ugn-docs/html/gnat_ugn/gnat_ugn.html [2] I've also used it for generating slides for Cauldron presentations: https://dmalcolm.fedorapeople.org/presentations/cauldron-2014/rtl/ https://dmalcolm.fedorapeople.org/presentations/cauldron-2014/jit/ and for gcc-python-plugin: https://gcc-python-plugin.readthedocs.org/en/latest/ I've written a tool called texi2rst which attempts to convert a .texi based document to .rst ("restructured text", the input format for Sphinx): https://github.com/davidmalcolm/texi2rst This is what generated the examples above. It doesn't *quite* do a direct .texi to .rst conversion yet: it can take the XML output from texinfo's "makeinfo --xml", and generate either one big .rst file, or a group of smaller .rst files. My hope was that for every gcc/docs/foo.texi file we have, my tool would be able to generate a gcc/docs/foo.rst (maybe retaining the name, to allow for sane diff and hence sane patch review). Unfortunately, "makeinfo --xml" resolves includes and conditional processing, so the underlying input structure of .texinfo files is lost at that point. To fix that, I've been working on a frontend from texi2rst that re-implements the .texi to xml processing, retaining information on includes, and directives, so that I can translate them to corresponding .rst directives. Unfortunately it's clear that I'm not going to finish that before stage 1 closes - but I think it's feasible in the stage3 timeframe. Hence in the example posted above, the doc is split into pages based on nodes, named after the nodes, and thus get rather long names e.g. options-that-control-optimization.html, generated from options-that-control-optimization.rst. In a more polished version, these names would be saner. The primary advantages of .rst/sphinx over .texi/texinfo I see are in the generated HTML: * sane, stable URLs (so e.g. there is a reliable URL for the docs for, say, "-Wall"). * a page-splitting structure that make sense, to me, at least [3] * much more use of markup, with restrained and well-chosen CSS (texinfo's HTML seems to ignore much of the inline markup in the .texinfo file) * autogenerated internal links, so that almost everything is clickable, and will take you somewhere sane, by default * syntax-highlighting of code examples, with support for multiple programming languages (note the mixture of C, C++, Fortran, etc in the docs for the gcc options). * looks modern and fresh (IMHO), letting casual observers see that the project is alive and kicking. Thoughts? Dave [1] http://sphinx-doc.org/ [2] I couldn't find Sphinx-built HTML for Ada on the gcc website, just the Texinfo output here: https://gcc.gnu.org/onlinedocs/gnat_ugn/index.html [3] I have never fathomed the way texinfo's navigation works, for HTML, at least, and I believe I'm not the only one; I generally pick the all-in-one-HTML-page option when viewing texinfo-html docs and do textual searches, since otherwise I usually can't find the thing I'm looking for (or have to resort to a brute-force depth-first search of clicking through the links).
