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
