Re: [PING, www] Re: [PATCH] update_web_docs_svn: support the JIT docs (PR jit/64257)

Re: [PING, www] Re: [PATCH] update_web_docs_svn: support the JIT docs (PR jit/64257)

[Gerald Pfeifer]

Hi David,

On Monday 2015-02-02 11:39, David Malcolm wrote:
>>>> 	* update_web_docs_svn: Don't delete gcc/jit/docs or
>>>> 	gcc/jit/jit-common.h, gcc/jit/notes.txt. Special case the
>>>> 	building of the jit docs (using sphinx-build).  Special case
>>>> 	copying them up.
>> I've committed this to trunk as r220149.
>> 
>> Does this automatically get propagated to the machine that builds the
>> website (and thus would be run next time the relevant cronjob runs)?

I looked into this, and it does not get propagated automatically,
so I did it manually (svn up at the proper location).

>> Or does someone need to do additional work for this to "go live"?  (if
>> nothing else, the machine needs to have sphinx-build in its $PATH, as
>> noted in the patch).
> I'm hoping to have the jit docs on the gcc website.

I guess we'll be testing the error handling behavior of your new
code :-), since indeed sphinx-build is not in the standard $PATH.

Do you know where it can be found on this machine?

> Presumably, some machine needs to have the relevant sphinx packaged
> installed (if that's OK [1]), and perhaps the update to the
> update_web_docs_svn script needs to make it onto that machine?
> 
> Or is this more appropriate for the "overseers" list?

Yes, please direct the request for sphinx to overseers.

(In parallel, if you can refine how the script behaves when sphinx
is not present, that might be a good idea, too.)

Gerald

Re: [PATCH] More fixes for update_web_docs_svn for jit docs (PR jit/64257)

[Gerald Pfeifer]

On Wednesday 2015-02-04 14:10, David Malcolm wrote:
> Gerald: Please can you do the "svn up" on the relevant machine again, 
> so that it gets the updated "update_web_docs_svn"?

That was my plan, yes. :-)  I just did that and manually ran
the script, and it seems to work.

Still, do you think you can add a bit of error handling such
that an issue like the one we had (cf. 
https://gcc.gnu.org/ml/gccadmin/2015-q1/msg00077.html ) does
not kill the entire script?  A bit of resilience would be good.

Gerald

Re: [PATCH] More fixes for update_web_docs_svn for jit docs (PR jit/64257)

[David Malcolm]

[-- Attachment #1: Type: text/plain, Size: 913 bytes --]

On Wed, 2015-02-04 at 22:21 +0100, Gerald Pfeifer wrote:
> On Wednesday 2015-02-04 14:10, David Malcolm wrote:
> > Gerald: Please can you do the "svn up" on the relevant machine again, 
> > so that it gets the updated "update_web_docs_svn"?
> 
> That was my plan, yes. :-)  I just did that and manually ran
> the script, and it seems to work.

Thank you!

The jit docs are now visible on the GCC website at:
  https://gcc.gnu.org/onlinedocs/jit/

(sadly the "Show Source" link on each page is a 404; iirc the "pyramid"
theme didn't show these links so I didn't bother copying up the files;
I'll look at fixing that).

> Still, do you think you can add a bit of error handling such
> that an issue like the one we had (cf. 
> https://gcc.gnu.org/ml/gccadmin/2015-q1/msg00077.html ) does
> not kill the entire script?  A bit of resilience would be good.

Something like the attached?  (completely untested, sorry)


[-- Attachment #2: or-true.patch --]
[-- Type: text/x-patch, Size: 538 bytes --]

diff --git a/maintainer-scripts/update_web_docs_svn b/maintainer-scripts/update_web_docs_svn
index e0132dc..c1ff903 100755
--- a/maintainer-scripts/update_web_docs_svn
+++ b/maintainer-scripts/update_web_docs_svn
@@ -180,7 +180,7 @@ done
 #   /usr/bin/sphinx-1.0-build
 # so we need to override SPHINXBUILD with this when invoking "make".
 pushd gcc/gcc/jit/docs
-make SPHINXBUILD=/usr/bin/sphinx-1.0-build html
+make SPHINXBUILD=/usr/bin/sphinx-1.0-build html || true
 popd
 cp -a gcc/gcc/jit/docs/_build/html jit
 mkdir -p $DOCSDIR/jit

Re: [PATCH] update_web_docs_svn: support the JIT docs (PR jit/64257)

[Mike Stump]

On Jan 26, 2015, at 3:43 AM, Gerald Pfeifer <gerald@pfeifer.com> wrote:
>> +# Again, the jit is a special case, with nested subdirectories
>> +# below "jit", and with some non-HTML files (.png images from us,
>> +# plus .js and .css supplied by sphinx).
>> +for file in $(find jit \
>> +                -name "*.html" -o -name "*.css" \
>> +                -o -name "*.js" -o -name "*.png"); do
> 
> This looks like a Bash-ism.  Can you use back ticks

http://pubs.opengroup.org/onlinepubs/9699919799/utilities/V3_chap02.html

$() is standard and preferred over back ticks.  :-)  Life goes on.

Re: [PATCH] maintainer-scripts: Fix 404s in "Show Source" in jit docs

[Gerald Pfeifer]

On Thursday 2015-02-05 22:49, David Malcolm wrote:
> Tested locally with a suitably hacked up script to work on this
> machine; with this patch the "Show Sources" links work within the
> files installed to /www/gcc/htdocs.
> 
> OK for trunk?
> 
> maintainer-scripts/ChangeLog:
> 	* update_web_docs_svn: When copying up files for the built jit
> 	documentation, also copy up .txt files.

Sure thing.  You should just consider yourself the maintainer of
this aspect and simply go ahead with changes like this.

Gerald

Re: [PATCH] update_web_docs_svn: support the JIT docs (PR jit/64257)

[Jeff Law]

On 01/26/15 09:42, David Malcolm wrote:

> update_web_docs_svn-support-the-JIT-documention-v2.patch
>
>
>  From 7f7e15881981228e51b347f23df6e3106ddd68ea Mon Sep 17 00:00:00 2001
> From: David Malcolm<dmalcolm@redhat.com>
> Date: Fri, 23 Jan 2015 17:26:57 -0500
> Subject: [PATCH] update_web_docs_svn: support the JIT documentation
>
> maintainer-scripts/ChangeLog:
> 	* update_web_docs_svn: Don't delete gcc/jit/docs or
> 	gcc/jit/jit-common.h, gcc/jit/notes.txt. Special case the
> 	building of the jit docs (using sphinx-build).  Special case
> 	copying them up.
OK.
jeff

Re: [PATCH] update_web_docs_svn: support the JIT docs (PR jit/64257)

[David Malcolm]

[-- Attachment #1: Type: text/plain, Size: 3055 bytes --]

On Mon, 2015-01-26 at 12:43 +0100, Gerald Pfeifer wrote:
> On Friday 2015-01-23 17:44, David Malcolm wrote:
> > The following patch builds and installs the JIT documentation for
> > the website (just HTML for now).
> > 
> > It's tricky to test (I don't have a copy of /www/gcc/bin/preprocess),
> > but I was able to use this to generate sane-looking documentation,
> > both for the .texi files, and for the JIT documentation.
> You can easily get the preprocess script by checking out wwwdocs,
> cf. https://gcc.gnu.org/about.html.

Thanks.

> That still will require MetaHTML which, sadly, became an abandoned
> FSF project, and will require a hack or two to build, so let's just
> go with your patch.
> 
> A few notes, though:
> 
> > maintainer-scripts/ChangeLog:
> > 	PR jit/64257
> > 	* update_web_docs_svn: Don't delete gcc/jit/docs,
> > 	since the jit docs are not .tex files (Makefile, .rst and
> > 	.png).	Special-case the building of the JIT docs (using
> > 	sphinx-build).  Special-case copying them up (since they
> > 	contain .css, .js and .png files in addition to .html, and
> > 	have nested subdirectories).
> 
> The "since" should be part of the code, not the ChangeLog.

Fair point; I've moved both of these to comments in the file.

> > diff --git a/maintainer-scripts/update_web_docs_svn b/maintainer-scripts/update_web_docs_svn
> > index c661220..c7eb890 100755
> > --- a/maintainer-scripts/update_web_docs_svn
> > +++ b/maintainer-scripts/update_web_docs_svn
> > +# The JIT is a special-case, using sphinx rather than texinfo.
> 
> special case

Fixed.

> > +# The jit Makefile uses "sphinx-build", which is packaged in
> > +# Fedora and EPEL 6 within "python-sphinx".
> 
> JIT (above) vs jit (here)?

I now use lowercase "jit" throughout.

> How about saying "...packaged in "python-sphinx" in Fedora and
> EPEL 6 and in "python-Sphinx" in openSUSE"?

Added.

> > +# Again, the jit is a special case, with nested subdirectories
> > +# below "jit", and with some non-HTML files (.png images from us,
> > +# plus .js and .css supplied by sphinx).
> > +for file in $(find jit \
> > +                -name "*.html" -o -name "*.css" \
> > +                -o -name "*.js" -o -name "*.png"); do
> 
> This looks like a Bash-ism.  Can you use backticks of something
> like 
> 
>   find ... | while read file; ...
> 
> ?

Done.

(Your proposal is superior since it avoids potentially long command
lines; but out of interest, why specifically avoid bash here?)

> > +    cp $file $DOCSDIR/$file
> 
> Just "cp $file $DOCSDIR/" ?  This one may be a better of style,
> but is easier to tweak in case we need to quote later on, for
> example.

The jit documentation has a nested directory structure (e.g. there are 7
instances of an "index.html" within them), "$file" actually will contain
a path to a file, so we do need to have $file on the right-hand side of
the cp command.

I've added a comment to clarify that.

I'm attaching a revised patch which I hope addresses these issues;
tested (crudely) as before.

How does this look?

Thanks
Dave

[-- Attachment #2: update_web_docs_svn-support-the-JIT-documention-v2.patch --]
[-- Type: text/x-patch, Size: 2741 bytes --]

From 7f7e15881981228e51b347f23df6e3106ddd68ea Mon Sep 17 00:00:00 2001
From: David Malcolm <dmalcolm@redhat.com>
Date: Fri, 23 Jan 2015 17:26:57 -0500
Subject: [PATCH] update_web_docs_svn: support the JIT documentation

maintainer-scripts/ChangeLog:
	* update_web_docs_svn: Don't delete gcc/jit/docs or
	gcc/jit/jit-common.h, gcc/jit/notes.txt. Special case the
	building of the jit docs (using sphinx-build).  Special case
	copying them up.
---
 maintainer-scripts/update_web_docs_svn | 30 ++++++++++++++++++++++++++++++
 1 file changed, 30 insertions(+)

diff --git a/maintainer-scripts/update_web_docs_svn b/maintainer-scripts/update_web_docs_svn
index c661220..ac3bae6 100755
--- a/maintainer-scripts/update_web_docs_svn
+++ b/maintainer-scripts/update_web_docs_svn
@@ -111,11 +111,18 @@ fi
 # generator programs with the installed library, not the new one and
 # (b) 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
+# jit/notes.txt, so we have to preserve those also.
 find gcc -type f \( -name '*.texi' \
   -o -path gcc/gcc/doc/install.texi2html \
   -o -path gcc/gcc/doc/include/texinfo.tex \
   -o -path gcc/gcc/BASE-VER \
   -o -path gcc/gcc/DEV-PHASE \
+  -o -path "gcc/gcc/jit/docs/*" \
+  -o -path "gcc/gcc/jit/jit-common.h" \
+  -o -path "gcc/gcc/jit/notes.txt" \
   -o -print0 \) | xargs -0 rm -f
 
 # Build a tarball of the sources.
@@ -158,6 +165,16 @@ for file in $MANUALS; do
   fi
 done
 
+# The jit is a special-case, using sphinx rather than texinfo.
+# The jit Makefile uses "sphinx-build".  This is packaged in
+# Fedora and EPEL 6 within "python-sphinx", and in openSUSE
+# within "python-Sphinx".
+pushd gcc/gcc/jit/docs
+make html
+popd
+cp -a gcc/gcc/jit/docs/_build/html jit
+mkdir -p $DOCSDIR/jit
+
 # Work around makeinfo generated file names and references with
 # "_002d" instead of "-".
 find . -name '*.html' | while read f; do
@@ -204,6 +221,19 @@ for file in */*.html *.ps *.pdf *.tar; do
   fi
 done
 
+# Again, the jit is a special case, with nested subdirectories
+# below "jit", and with some non-HTML files (.png images from us,
+# plus .css and .js supplied by sphinx).
+find jit \
+    -name "*.html" -o -name "*.png" \
+    -o -name "*.css" -o -name "*.js" |
+  while read file ; do
+    # Note that $file here will contain path fragments beginning
+    # with "jit/", e.g. "jit/cp/topics/functions.html"
+    mkdir -p $(dirname $DOCSDIR/$file)
+    cp $file $DOCSDIR/$file
+  done
+
 cd $DOCSDIR
 
 # Finally, generate the installation documentation
-- 
1.8.5.3

Re: [PATCH] More fixes for update_web_docs_svn for jit docs (PR jit/64257)

[Andrew Pinski]

On Wed, Feb 4, 2015 at 10:32 AM, David Malcolm <dmalcolm@redhat.com> wrote:
> To build the jit docs, we need to use sphinx 1.0 or later; the
> 0.6.6 in EPEL 6 doesn't support all the directives we need.
>
> The alternate python-sphinx10 in EPEL 6 has 1.0.8:
>   python-sphinx10-1.0.8-1.el6.noarch
> which is able to build the jit docs, apart from not having the
> "pyramid" theme (this theme appears to have been added in 1.1).
>
> Change the theme to "sphinxdoc", which seems to be the most
> attractive theme in 1.0.8 (FWIW, it appears that LLVM are using
> a custom variant of this sphinx theme for the docs on their
> website).
>
> I was able to use these changes to run the jit docs Makefile on
> sourceware.org; the generated HTML can be seen at:
> https://dmalcolm.fedorapeople.org/gcc/2015-02-04/jit-docs-sphinxdocs/

Can you document this in https://gcc.gnu.org/install/prerequisites.html ?
Also can you make sure that release script creates the precreates
documentation so people don't need to install something else to
install GCC (releases don't need makeinfo to install).

Thanks,
Andrew


>
> OK for trunk?
>
> gcc/jit/ChangeLog:
>         PR jit/64257
>         * docs/conf.py (html_theme): Change from 'pyramid'
>         to 'sphinxdoc'.
>
> maintainer-scripts/ChangeLog:
>         PR jit/64257
>         * update_web_docs_svn: Update build of jit docs to use EPEL6
>         variant install of sphinx 1.0.8, rather than 0.6.6.
> ---
>  gcc/jit/docs/conf.py                   |  2 +-
>  maintainer-scripts/update_web_docs_svn | 18 ++++++++++++++----
>  2 files changed, 15 insertions(+), 5 deletions(-)
>
> diff --git a/gcc/jit/docs/conf.py b/gcc/jit/docs/conf.py
> index 1bdc081..8f4dd8b 100644
> --- a/gcc/jit/docs/conf.py
> +++ b/gcc/jit/docs/conf.py
> @@ -107,7 +107,7 @@ pygments_style = 'sphinx'
>
>  # The theme to use for HTML and HTML Help pages.  See the documentation for
>  # a list of builtin themes.
> -html_theme = 'pyramid'
> +html_theme = 'sphinxdoc'
>
>  # Theme options are theme-specific and customize the look and feel of a theme
>  # further.  For a list of options available for each theme, see the
> diff --git a/maintainer-scripts/update_web_docs_svn b/maintainer-scripts/update_web_docs_svn
> index ac3bae6..e0132dc 100755
> --- a/maintainer-scripts/update_web_docs_svn
> +++ b/maintainer-scripts/update_web_docs_svn
> @@ -166,11 +166,21 @@ for file in $MANUALS; do
>  done
>
>  # The jit is a special-case, using sphinx rather than texinfo.
> -# The jit Makefile uses "sphinx-build".  This is packaged in
> -# Fedora and EPEL 6 within "python-sphinx", and in openSUSE
> -# within "python-Sphinx".
> +# Specifically, the jit docs need sphinx 1.0 or later.
> +#
> +# The jit/docs Makefile uses the executable $(SPHINXBUILD),
> +# defaulting to "sphinx-build".
> +#
> +# sphinx is packaged in Fedora and EPEL 6 within "python-sphinx",
> +# and in openSUSE within "python-Sphinx".
> +#
> +# For EPEL6, python-sphinx is sphinx 0.6.6, which is missing various
> +# directives (e.g. ":c:macro:"), so we need the variant
> +# python-sphinx10 package.  The latter installs its executable as:
> +#   /usr/bin/sphinx-1.0-build
> +# so we need to override SPHINXBUILD with this when invoking "make".
>  pushd gcc/gcc/jit/docs
> -make html
> +make SPHINXBUILD=/usr/bin/sphinx-1.0-build html
>  popd
>  cp -a gcc/gcc/jit/docs/_build/html jit
>  mkdir -p $DOCSDIR/jit
> --
> 1.8.5.3
>

Re: [PATCH] update_web_docs_svn: support the JIT docs (PR jit/64257)

[David Malcolm]

On Mon, 2015-01-26 at 15:21 -0700, Jeff Law wrote:
> On 01/26/15 09:42, David Malcolm wrote:
> 
> > update_web_docs_svn-support-the-JIT-documention-v2.patch
> >
> >
> >  From 7f7e15881981228e51b347f23df6e3106ddd68ea Mon Sep 17 00:00:00 2001
> > From: David Malcolm<dmalcolm@redhat.com>
> > Date: Fri, 23 Jan 2015 17:26:57 -0500
> > Subject: [PATCH] update_web_docs_svn: support the JIT documentation
> >
> > maintainer-scripts/ChangeLog:
> > 	* update_web_docs_svn: Don't delete gcc/jit/docs or
> > 	gcc/jit/jit-common.h, gcc/jit/notes.txt. Special case the
> > 	building of the jit docs (using sphinx-build).  Special case
> > 	copying them up.
> OK.

Thanks.

I've committed this to trunk as r220149.

Does this automatically get propagated to the machine that builds the
website (and thus would be run next time the relevant cronjob runs)?
Or does someone need to do additional work for this to "go live"?  (if
nothing else, the machine needs to have sphinx-build in its $PATH, as
noted in the patch).

Dave

[PATCH] maintainer-scripts: Fix 404s in "Show Source" in jit docs

[David Malcolm]

Tested locally with a suitably hacked up script to work on this
machine; with this patch the "Show Sources" links work within the
files installed to /www/gcc/htdocs.

OK for trunk?

maintainer-scripts/ChangeLog:
	* update_web_docs_svn: When copying up files for the built jit
	documentation, also copy up .txt files.
---
 maintainer-scripts/update_web_docs_svn | 6 ++++--
 1 file changed, 4 insertions(+), 2 deletions(-)

diff --git a/maintainer-scripts/update_web_docs_svn b/maintainer-scripts/update_web_docs_svn
index 2544211..7832eed 100755
--- a/maintainer-scripts/update_web_docs_svn
+++ b/maintainer-scripts/update_web_docs_svn
@@ -233,10 +233,12 @@ done
 
 # Again, the jit is a special case, with nested subdirectories
 # below "jit", and with some non-HTML files (.png images from us,
-# plus .css and .js supplied by sphinx).
+# plus .css and .js supplied by sphinx, and source files, renamed
+# from .rst to .txt).
 find jit \
     -name "*.html" -o -name "*.png" \
-    -o -name "*.css" -o -name "*.js" |
+    -o -name "*.css" -o -name "*.js" \
+    -o -name "*.txt" |
   while read file ; do
     # Note that $file here will contain path fragments beginning
     # with "jit/", e.g. "jit/cp/topics/functions.html"
-- 
1.8.5.3

Re: [PATCH] More fixes for update_web_docs_svn for jit docs (PR jit/64257)

[Gerald Pfeifer]

On Wednesday 2015-02-04 13:32, David Malcolm wrote:
> OK for trunk?
> 
> gcc/jit/ChangeLog:
> 	PR jit/64257
> 	* docs/conf.py (html_theme): Change from 'pyramid'
> 	to 'sphinxdoc'.
> 
> maintainer-scripts/ChangeLog:
> 	PR jit/64257
> 	* update_web_docs_svn: Update build of jit docs to use EPEL6
> 	variant install of sphinx 1.0.8, rather than 0.6.6.

Yes.

> +# python-sphinx10 package.  The latter installs its executable as:

Here I'd omit the colon, but that is more of a stylistic question
I guess.

Gerald

[PATCH] update_web_docs_svn: support the JIT docs (PR jit/64257)

[David Malcolm]

The following patch builds and installs the JIT documentation for
the website (just HTML for now).

It's tricky to test (I don't have a copy of /www/gcc/bin/preprocess),
but I was able to use this to generate sane-looking documentation,
both for the .texi files, and for the JIT documentation.

Tested on Fedora 20, using python-sphinx-1.1.3-9.fc20.noarch.

I believe python-sphinx is in EPEL 6, fwiw.

maintainer-scripts/ChangeLog:
	PR jit/64257
	* update_web_docs_svn: Don't delete gcc/jit/docs,
	since the jit docs are not .tex files (Makefile, .rst and
	.png).	Special-case the building of the JIT docs (using
	sphinx-build).  Special-case copying them up (since they
	contain .css, .js and .png files in addition to .html, and
	have nested subdirectories).
---
 maintainer-scripts/update_web_docs_svn | 20 ++++++++++++++++++++
 1 file changed, 20 insertions(+)

diff --git a/maintainer-scripts/update_web_docs_svn b/maintainer-scripts/update_web_docs_svn
index c661220..c7eb890 100755
--- a/maintainer-scripts/update_web_docs_svn
+++ b/maintainer-scripts/update_web_docs_svn
@@ -116,6 +116,7 @@ find gcc -type f \( -name '*.texi' \
   -o -path gcc/gcc/doc/include/texinfo.tex \
   -o -path gcc/gcc/BASE-VER \
   -o -path gcc/gcc/DEV-PHASE \
+  -o -path "gcc/gcc/jit/docs/*" \
   -o -print0 \) | xargs -0 rm -f
 
 # Build a tarball of the sources.
@@ -158,6 +159,15 @@ for file in $MANUALS; do
   fi
 done
 
+# The JIT is a special-case, using sphinx rather than texinfo.
+# The jit Makefile uses "sphinx-build", which is packaged in
+# Fedora and EPEL 6 within "python-sphinx".
+pushd gcc/gcc/jit/docs
+make html
+popd
+cp -a gcc/gcc/jit/docs/_build/html jit
+mkdir -p $DOCSDIR/jit
+
 # Work around makeinfo generated file names and references with
 # "_002d" instead of "-".
 find . -name '*.html' | while read f; do
@@ -204,6 +214,16 @@ for file in */*.html *.ps *.pdf *.tar; do
   fi
 done
 
+# Again, the jit is a special case, with nested subdirectories
+# below "jit", and with some non-HTML files (.png images from us,
+# plus .js and .css supplied by sphinx).
+for file in $(find jit \
+                -name "*.html" -o -name "*.css" \
+                -o -name "*.js" -o -name "*.png"); do
+    mkdir -p $(dirname $DOCSDIR/$file)
+    cp $file $DOCSDIR/$file
+done
+
 cd $DOCSDIR
 
 # Finally, generate the installation documentation
-- 
1.8.5.3

Re: [PATCH] update_web_docs_svn: support the JIT docs (PR jit/64257)

[Gerald Pfeifer]

On Friday 2015-01-23 17:44, David Malcolm wrote:
> The following patch builds and installs the JIT documentation for
> the website (just HTML for now).
> 
> It's tricky to test (I don't have a copy of /www/gcc/bin/preprocess),
> but I was able to use this to generate sane-looking documentation,
> both for the .texi files, and for the JIT documentation.

You can easily get the preprocess script by checking out wwwdocs,
cf. https://gcc.gnu.org/about.html.

That still will require MetaHTML which, sadly, became an abandoned
FSF project, and will require a hack or two to build, so let's just
go with your patch.

A few notes, though:

> maintainer-scripts/ChangeLog:
> 	PR jit/64257
> 	* update_web_docs_svn: Don't delete gcc/jit/docs,
> 	since the jit docs are not .tex files (Makefile, .rst and
> 	.png).	Special-case the building of the JIT docs (using
> 	sphinx-build).  Special-case copying them up (since they
> 	contain .css, .js and .png files in addition to .html, and
> 	have nested subdirectories).

The "since" should be part of the code, not the ChangeLog.

> diff --git a/maintainer-scripts/update_web_docs_svn b/maintainer-scripts/update_web_docs_svn
> index c661220..c7eb890 100755
> --- a/maintainer-scripts/update_web_docs_svn
> +++ b/maintainer-scripts/update_web_docs_svn
> +# The JIT is a special-case, using sphinx rather than texinfo.

special case

> +# The jit Makefile uses "sphinx-build", which is packaged in
> +# Fedora and EPEL 6 within "python-sphinx".

JIT (above) vs jit (here)?

How about saying "...packaged in "python-sphinx" in Fedora and
EPEL 6 and in "python-Sphinx" in openSUSE"?

> +# Again, the jit is a special case, with nested subdirectories
> +# below "jit", and with some non-HTML files (.png images from us,
> +# plus .js and .css supplied by sphinx).
> +for file in $(find jit \
> +                -name "*.html" -o -name "*.css" \
> +                -o -name "*.js" -o -name "*.png"); do

This looks like a Bash-ism.  Can you use backticks of something
like 

  find ... | while read file; ...

?

> +    cp $file $DOCSDIR/$file

Just "cp $file $DOCSDIR/" ?  This one may be a better of style,
but is easier to tweak in case we need to quote later on, for
example.

Gerald

[PING, www] Re: [PATCH] update_web_docs_svn: support the JIT docs (PR jit/64257)

[David Malcolm]

On Mon, 2015-01-26 at 19:14 -0500, David Malcolm wrote:
> On Mon, 2015-01-26 at 15:21 -0700, Jeff Law wrote:
> > On 01/26/15 09:42, David Malcolm wrote:
> > 
> > > update_web_docs_svn-support-the-JIT-documention-v2.patch
> > >
> > >
> > >  From 7f7e15881981228e51b347f23df6e3106ddd68ea Mon Sep 17 00:00:00 2001
> > > From: David Malcolm<dmalcolm@redhat.com>
> > > Date: Fri, 23 Jan 2015 17:26:57 -0500
> > > Subject: [PATCH] update_web_docs_svn: support the JIT documentation
> > >
> > > maintainer-scripts/ChangeLog:
> > > 	* update_web_docs_svn: Don't delete gcc/jit/docs or
> > > 	gcc/jit/jit-common.h, gcc/jit/notes.txt. Special case the
> > > 	building of the jit docs (using sphinx-build).  Special case
> > > 	copying them up.
> > OK.
> 
> Thanks.
> 
> I've committed this to trunk as r220149.
> 
> Does this automatically get propagated to the machine that builds the
> website (and thus would be run next time the relevant cronjob runs)?
> Or does someone need to do additional work for this to "go live"?  (if
> nothing else, the machine needs to have sphinx-build in its $PATH, as
> noted in the patch).

Ping re ^^^^^

I'm hoping to have the jit docs on the gcc website.

In the best of all worlds, with r220149, the jit docs might have
appeared at:
  https://gcc.gnu.org/onlinedocs/jit
but that's currently a 404.

Presumably, some machine needs to have the relevant sphinx packaged
installed (if that's OK [1]), and perhaps the update to the
update_web_docs_svn script needs to make it onto that machine?

Or is this more appropriate for the "overseers" list?

Thanks
Dave

[1] otherwise, do I need to look into another way of getting the docs
built for the site?

Re: [PATCH] More fixes for update_web_docs_svn for jit docs (PR jit/64257)

[David Malcolm]

On Wed, 2015-02-04 at 19:47 +0100, Gerald Pfeifer wrote:
> On Wednesday 2015-02-04 13:32, David Malcolm wrote:
> > OK for trunk?
> > 
> > gcc/jit/ChangeLog:
> > 	PR jit/64257
> > 	* docs/conf.py (html_theme): Change from 'pyramid'
> > 	to 'sphinxdoc'.
> > 
> > maintainer-scripts/ChangeLog:
> > 	PR jit/64257
> > 	* update_web_docs_svn: Update build of jit docs to use EPEL6
> > 	variant install of sphinx 1.0.8, rather than 0.6.6.
> 
> Yes.
> 
> > +# python-sphinx10 package.  The latter installs its executable as:
> 
> Here I'd omit the colon, but that is more of a stylistic question
> I guess.

Thanks. I've committed it to svn trunk as r220412, omitting the colon.

Gerald: Please can you do the "svn up" on the relevant machine again, so
that it gets the updated "update_web_docs_svn"?

Hopefully this will fix the cronjob...

Dave

[PATCH] More fixes for update_web_docs_svn for jit docs (PR jit/64257)

[David Malcolm]

To build the jit docs, we need to use sphinx 1.0 or later; the
0.6.6 in EPEL 6 doesn't support all the directives we need.

The alternate python-sphinx10 in EPEL 6 has 1.0.8:
  python-sphinx10-1.0.8-1.el6.noarch
which is able to build the jit docs, apart from not having the
"pyramid" theme (this theme appears to have been added in 1.1).

Change the theme to "sphinxdoc", which seems to be the most
attractive theme in 1.0.8 (FWIW, it appears that LLVM are using
a custom variant of this sphinx theme for the docs on their
website).

I was able to use these changes to run the jit docs Makefile on
sourceware.org; the generated HTML can be seen at:
https://dmalcolm.fedorapeople.org/gcc/2015-02-04/jit-docs-sphinxdocs/

OK for trunk?

gcc/jit/ChangeLog:
	PR jit/64257
	* docs/conf.py (html_theme): Change from 'pyramid'
	to 'sphinxdoc'.

maintainer-scripts/ChangeLog:
	PR jit/64257
	* update_web_docs_svn: Update build of jit docs to use EPEL6
	variant install of sphinx 1.0.8, rather than 0.6.6.
---
 gcc/jit/docs/conf.py                   |  2 +-
 maintainer-scripts/update_web_docs_svn | 18 ++++++++++++++----
 2 files changed, 15 insertions(+), 5 deletions(-)

diff --git a/gcc/jit/docs/conf.py b/gcc/jit/docs/conf.py
index 1bdc081..8f4dd8b 100644
--- a/gcc/jit/docs/conf.py
+++ b/gcc/jit/docs/conf.py
@@ -107,7 +107,7 @@ pygments_style = 'sphinx'
 
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
-html_theme = 'pyramid'
+html_theme = 'sphinxdoc'
 
 # Theme options are theme-specific and customize the look and feel of a theme
 # further.  For a list of options available for each theme, see the
diff --git a/maintainer-scripts/update_web_docs_svn b/maintainer-scripts/update_web_docs_svn
index ac3bae6..e0132dc 100755
--- a/maintainer-scripts/update_web_docs_svn
+++ b/maintainer-scripts/update_web_docs_svn
@@ -166,11 +166,21 @@ for file in $MANUALS; do
 done
 
 # The jit is a special-case, using sphinx rather than texinfo.
-# The jit Makefile uses "sphinx-build".  This is packaged in
-# Fedora and EPEL 6 within "python-sphinx", and in openSUSE
-# within "python-Sphinx".
+# Specifically, the jit docs need sphinx 1.0 or later.
+#
+# The jit/docs Makefile uses the executable $(SPHINXBUILD),
+# defaulting to "sphinx-build".
+#
+# sphinx is packaged in Fedora and EPEL 6 within "python-sphinx",
+# and in openSUSE within "python-Sphinx".
+#
+# For EPEL6, python-sphinx is sphinx 0.6.6, which is missing various
+# directives (e.g. ":c:macro:"), so we need the variant
+# python-sphinx10 package.  The latter installs its executable as:
+#   /usr/bin/sphinx-1.0-build
+# so we need to override SPHINXBUILD with this when invoking "make".
 pushd gcc/gcc/jit/docs
-make html
+make SPHINXBUILD=/usr/bin/sphinx-1.0-build html
 popd
 cp -a gcc/gcc/jit/docs/_build/html jit
 mkdir -p $DOCSDIR/jit
-- 
1.8.5.3

Re: [PATCH] More fixes for update_web_docs_svn for jit docs (PR jit/64257)

[David Malcolm]

On Wed, 2015-02-04 at 17:26 -0500, David Malcolm wrote:
> On Wed, 2015-02-04 at 22:21 +0100, Gerald Pfeifer wrote:
> > On Wednesday 2015-02-04 14:10, David Malcolm wrote:
> > > Gerald: Please can you do the "svn up" on the relevant machine again, 
> > > so that it gets the updated "update_web_docs_svn"?
> > 
> > That was my plan, yes. :-)  I just did that and manually ran
> > the script, and it seems to work.
> 
> Thank you!
> 
> The jit docs are now visible on the GCC website at:
>   https://gcc.gnu.org/onlinedocs/jit/

and fwiw:
  https://gcc.gnu.org/ml/gccadmin/2015-q1/msg00080.html
shows that the cronjob then successfully rebuilt them again from svn.

> (sadly the "Show Source" link on each page is a 404; iirc the "pyramid"
> theme didn't show these links so I didn't bother copying up the files;
> I'll look at fixing that).
> 
> > Still, do you think you can add a bit of error handling such
> > that an issue like the one we had (cf. 
> > https://gcc.gnu.org/ml/gccadmin/2015-q1/msg00077.html ) does
> > not kill the entire script?  A bit of resilience would be good.
> 
> Something like the attached?  (completely untested, sorry)
> 

Re: [PATCH] More fixes for update_web_docs_svn for jit docs (PR jit/64257)

[Gerald Pfeifer]

On Wed, 4 Feb 2015, David Malcolm wrote:
>> That was my plan, yes. :-)  I just did that and manually ran
>> the script, and it seems to work.
> Thank you!

>> Still, do you think you can add a bit of error handling such
>> that an issue like the one we had (cf. 
>> https://gcc.gnu.org/ml/gccadmin/2015-q1/msg00077.html ) does
>> not kill the entire script?  A bit of resilience would be good.
> Something like the attached?  (completely untested, sorry)

Yes.

Given that this was a while ago (ahem), I went ahead, created a
ChangeLog entry, committed the patch on your behalf, updated the
version on gcc.gnu.org, and did a test run there.

Gerald


2019-08-05  David Malcolm  <dmalcolm@redhat.com>

	* update_web_docs_svn: Proceed even if the invocation of
	sphinx fails.

Index: update_web_docs_svn
===================================================================
--- update_web_docs_svn	(revision 274098)
+++ update_web_docs_svn	(working copy)
@@ -190,7 +190,7 @@ done
 #   /usr/bin/sphinx-1.0-build
 # so we need to override SPHINXBUILD with this when invoking "make".
 pushd gcc/gcc/jit/docs
-make SPHINXBUILD=/usr/bin/sphinx-1.0-build html
+make SPHINXBUILD=/usr/bin/sphinx-1.0-build html || true
 popd
 cp -a gcc/gcc/jit/docs/_build/html jit
 mkdir -p $DOCSDIR/jit