This is the mail archive of the gcc@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: use of sphinx/rest as source for GNAT doc


On Fri, 2014-05-23 at 17:23 +0200, Arnaud Charlet wrote:
> At AdaCore, we have switched most of our product documentation the
> rest/sphinx format: http://sphinx-doc.org/
> which provides most of the advantages of texinfo (text format,
> can generate output in multiple formats, supported by free software), as well
> as additional advantages, at least for us (more modern output, actively
> maintained, support more output formats, simpler syntax).
> 
> So we are investigating converting also the GNAT documentation
> (GNAT User's Guide and GNAT RM) to this format.
> 
> I understand that GCC as whole likely wants to stick with texinfo
> for the time being, so I'm not really suggesting a switch here, but
> what about the following approach:
> 
> - the GNAT doc source would be in rest format (.rst files) instead
>   of texinfo (.texi files)
> - we would still provide .texi files, generated automatically by the
>   sphinx toolset (via 'make texinfo') and committed in the repository
>   (similarly to configure vs configure.in/aclocal.m4), so end users
>   would not have any extra dependency, and generation of documentation
>   would still be possible from the .texi files directly
> 
> What do people think in principle about the above proposal?
> Would that be an acceptable move for the GCC project?

FWIW I too use sphinx and .rst, for the gcc-python-plugin:
  https://gcc-python-plugin.readthedocs.org/en/latest/index.html
and for pygccjit, the python bindings to the JIT branch:
  http://pygccjit.readthedocs.org/en/latest/

[the above both use a custom "skin" provided by readthedocs.org, but the
default looks great also].

[For that matter the LLVM project uses sphinx also].

Having used both sphinx and texinfo, I find that Sphinx is far superior
to texinfo in both the editing experience (emacs has modes for both .rst
and .texi) and in the quality of the generated HTML (e.g. stable,
readable URLs).

My 2 cents
Dave



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