[Ada] convert GNAT doc to sphinx

> > I've added a -I gcc/gcc/ada/doc/gnat_ugn there, that's as far as my
> > knowledge goes for this script so I hope this is enough.
> 
> Well, since by default the find command deletes all files except those
> known to be documentation sources, you need at least to change it not to
> delete those particular files (and the actual RST sources of these
> manuals).

OK, I've applied the patch below, hopefully it should do the job.

> > I can help in transitioning the script to sphinx though, that would seem
> > more interesting/productive at this stage.
> 
> See the existing code to handle Sphinx documentation for the JIT.

That's a good reference. We'll need a more recent version of sphinx than
1.0 though (at least 1.2.2, or even better, 1.3b2 which is the version we use
at AdaCore).

Arno
--

On Wed, 25 Feb 2015, Arnaud Charlet wrote:

> > See the existing code to handle Sphinx documentation for the JIT.
> 
> That's a good reference. We'll need a more recent version of sphinx than
> 1.0 though (at least 1.2.2, or even better, 1.3b2 which is the version we use
> at AdaCore).

1.0 is apparently the most recent version readily available for RHEL 6 
which gcc.gnu.org runs.

On Wed, 2015-02-25 at 16:47 +0100, Arnaud Charlet wrote:
> > > I've added a -I gcc/gcc/ada/doc/gnat_ugn there, that's as far as my
> > > knowledge goes for this script so I hope this is enough.
> > 
> > Well, since by default the find command deletes all files except those
> > known to be documentation sources, you need at least to change it not to
> > delete those particular files (and the actual RST sources of these
> > manuals).
> 
> OK, I've applied the patch below, hopefully it should do the job.

Thanks for working on this.  I'm a big fan of sphinx (both for its ease
of use, and the quality of the generated HTML), and I hope that more GNU
documentation transitions to it.  (I actually *enjoy* writing docs using
sphinx, which I can't say for other toolchains).  As noted below, I'm
using it for libgccjit.

> > > I can help in transitioning the script to sphinx though, that would seem
> > > more interesting/productive at this stage.
> > 
> > See the existing code to handle Sphinx documentation for the JIT.
> 
> That's a good reference. 

You may also want to look at the bug I used to track the jit work:
  https://gcc.gnu.org/bugzilla/show_bug.cgi?id=64257
(aka "JIT documentation is not yet on the GCC website"), though
hopefully the pertinent information is now all in comments in the
update_web_docs_svn script.

> We'll need a more recent version of sphinx than
> 1.0 though (at least 1.2.2, or even better, 1.3b2 which is the version we use
> at AdaCore).

The specific version of sphinx in use for gcc.gnu.org is 1.0.8, from
EPEL6, which installs sphinx's executable to
  /usr/bin/sphinx-1.0-build
(the default RHEL6 /usr/bin/sphinx-build is for sphinx 0.6.6).

FWIW, I've filed:
  https://bugzilla.redhat.com/show_bug.cgi?id=1189218
to request a more recent version of sphinx in EPEL6 (i.e. beyond 1.0.8).
The jit just needs 1.0, but I'd prefer the "pyramid" theme (added in
1.1) to the one currently in use ("sphinxdoc").  We could even have a
gcc or gnu-specific theme (llvm has one, fwiw), but let's walk before we
run :)

gcc/doc/install.texi currently has:

  @item Sphinx version 1.0 (or later)

  Necessary to regenerate @file{jit/docs/_build/texinfo} from the @file{.rst}
  files in the directories below @file{jit/docs}.

so that too would need updating if you want to bump the minimum
requirement.

> --- update_web_docs_svn (revision 220961)
> +++ update_web_docs_svn (working copy)
> @@ -107,10 +107,8 @@
>    svn -q export $SVNROOT/tags/$RELEASE gcc
>  fi
>  
> -# Remove all unwanted files.  This is needed (a) to build the Ada
> -# generator programs with the installed library, not the new one and
> -# (b) to avoid packaging all the sources instead of only documentation
> -# sources.
> +# Remove all unwanted files.  This is needed to avoid packaging all the
> +# sources instead of only documentation sources.
>  # Note that we have to preserve gcc/jit/docs since the jit docs are
>  # not .texi files (Makefile, .rst and .png), and the jit docs use
>  # include directives to pull in content from jit/jit-common.h and
> @@ -120,6 +118,7 @@
>    -o -path gcc/gcc/doc/include/texinfo.tex \
>    -o -path gcc/gcc/BASE-VER \
>    -o -path gcc/gcc/DEV-PHASE \
> +  -o -path "gcc/gcc/ada/doc/gnat_ugn/*.png" \
>    -o -path "gcc/gcc/jit/docs/*" \
>    -o -path "gcc/gcc/jit/jit-common.h" \
>    -o -path "gcc/gcc/jit/notes.txt" \

How are you testing this?  When getting the jit docs to work I had to
hack up the script somewhat to be able to test it on a development box
(e.g. to cut back "MANUALS" to just libcpp to speed up testing).

Don't you also need to preserve the Makefile at this stage, and indeed
the .rst files?

To get sphinx-generated HTML for the jit onto the gcc website, I needed
to patch the script in three places:
  * the part above,
  * to add an invocation of the Makefile, and
  * to implement the copying up from the build location to the install
location (since the jit docs have nested subdirectories, plus .js
and .css files provided by sphinx).

Hope this is helpful
Dave

Thanks for your feedback, very useful!

> How are you testing this?  When getting the jit docs to work I had to
> hack up the script somewhat to be able to test it on a development box
> (e.g. to cut back "MANUALS" to just libcpp to speed up testing).

That's a good question. Truth is that so far I'm not since I do not know
how to test it :-) That's why I wanted to minimize my changes and was asking
for help, since testing these changes is not very practical/easy.

> Don't you also need to preserve the Makefile at this stage, and indeed
> the .rst files?

When we'll switch the script to using sphinx for GNAT docs, yes.

For now the temporary state is that we're still building docs from the
.texi files (now generated by sphinx). Certainly not ideal but it more or
less does the job.

> To get sphinx-generated HTML for the jit onto the gcc website, I needed
> to patch the script in three places:
>   * the part above,
>   * to add an invocation of the Makefile, and
>   * to implement the copying up from the build location to the install
> location (since the jit docs have nested subdirectories, plus .js
> and .css files provided by sphinx).

Makes sense.

> Hope this is helpful

It definitely is!

Arno

On Feb 26, 2015, at 9:07 AM, David Malcolm <dmalcolm@redhat.com> wrote:
>> We'll need a more recent version of sphinx than
>> 1.0 though (at least 1.2.2, or even better, 1.3b2 which is the version we use
>> at AdaCore).
> 
> The specific version of sphinx in use for gcc.gnu.org is 1.0.8

So, if people check in the generated files, then I think we should just bump the version required up to one that works well.  The people that want to regen will need to ensure they update, but that seems reasonable.

> gcc/doc/install.texi currently has:
> 
>  @item Sphinx version 1.0 (or later)
> 
>  Necessary to regenerate @file{jit/docs/_build/texinfo} from the @file{.rst}
>  files in the directories below @file{jit/docs}.
> 
> so that too would need updating if you want to bump the minimum
> requirement.