This is the mail archive of the gcc-patches@gcc.gnu.org mailing list for the GCC project.


Index Nav: [Date Index] [Subject Index] [Author Index] [Thread Index]
Message Nav: [Date Prev] [Date Next] [Thread Prev] [Thread Next]
Other format: [Raw text]

Re: RFC: Experimental use of Sphinx for GCC documentation


Hi David,

On 08/11/15 13:55, David Malcolm wrote:
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

FWIW, I think this all looks much better than the existing formatting.
One weird artifact I noticed while looking at the ARM options:
https://dmalcolm.fedorapeople.org/gcc/2015-08-31/rst-experiment/hardware-models-and-configurations.html#arm-options
In particular for -mcpu where it gives an explanation of what -mcpu=generic-<arch> is equivalent to, there seems
to be something weird going on.
The .texi source is:
@option{-mcpu=generic-@var{arch}} is also permissible, and is equivalent to @option{-march=@var{arch} -mtune=generic-@var{arch}}.

Whereas the output looks something like:
-mcpu=generic-``arch`` is also permissible, and is equivalent to -march=``arch` -mtune=generic-arch`

The backticks look somewhat inconsistent. But that may be due to invalid use of the @var and @option
constructs in the source. I'm not very familiar with the details.

Thanks,
Kyrill

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).



Index Nav: [Date Index] [Subject Index] [Author Index] [Thread Index]
Message Nav: [Date Prev] [Date Next] [Thread Prev] [Thread Next]