Getting libgccjit docs onto gcc website

Getting libgccjit docs onto gcc website

[David Malcolm]

A new feature in gcc 5 will be libgccjit:
  https://gcc.gnu.org/wiki/JIT

I'm trying to get the HTML docs for the jit onto the gcc website.

The jit documentation is built using Sphinx, rather than Texinfo.  An
example of the generated HTML can be seen at:
https://dmalcolm.fedorapeople.org/gcc/libgccjit-api-docs-wip/

To support this, I committed a patch to gcc's:
   maintainer-scripts/update_web_docs_svn
 https://gcc.gnu.org/ml/gcc-patches/2015-01/msg02293.html

to trunk as r220149:
 https://gcc.gnu.org/ml/gcc-patches/2015-02/msg00066.html
https://gcc.gnu.org/viewcvs/gcc/trunk/maintainer-scripts/update_web_docs_svn?r1=220149&r2=220148&pathrev=220149


In https://gcc.gnu.org/ml/gcc-patches/2015-02/msg00072.html, 
Gerald Pfeifer said:
> I looked into this, and it does not get propagated
> automatically,
> so I did it manually (svn up at the proper location).

The script is apparently run from a cronjob on the machine that builds
the gcc website, which appears to be run once a day (based on the
crontab file).

For this to work, the machine that builds the site needs to have
sphinx-build in the $PATH when the cronjob runs.

In theory, if it's all working properly, the jit docs ought to be built
and appear at:
  https://gcc.gnu.org/onlinedocs/jit
but that's currently a 404.

I don't have access to the cronjob logs, but presumably it will
currently be failing with a missing "sphinx-build".

FWIW, sphinx-build is packaged in Fedora and EPEL 6 within
"python-sphinx", and in openSUSE within "python-Sphinx".

It's written in python, there are various python dependencies.

Is this something that can be installed on the relevant machine (I'm not
an overseer) or do I need to come up with another approach for getting
the jit docs onto the gcc website? (e.g. an rsync from yet another
machine, or somesuch?)

I'm not an overseers list subscriber, so please keep me CCed on any
replies.  I'm lurking in the IRC channel fwiw.

Thanks!
Dave

Re: Getting libgccjit docs onto gcc website

[Frank Ch. Eigler]

Hi -

On Tue, Feb 03, 2015 at 02:58:49PM -0500, David Malcolm wrote:
> [...]
> For this to work, the machine that builds the site needs to have
> sphinx-build in the $PATH when the cronjob runs. [...]

OK, python-sphynx and prereqs installed.

- FChE

Re: Getting libgccjit docs onto gcc website

[Joseph Myers]

On Tue, 3 Feb 2015, David Malcolm wrote:

> I don't have access to the cronjob logs, but presumably it will
> currently be failing with a missing "sphinx-build".

You do have access: https://gcc.gnu.org/ml/gccadmin/ (that's why gccadmin 
is a mailing list, to provide access to those logs).

-- 
Joseph S. Myers
joseph@codesourcery.com

Re: Getting libgccjit docs onto gcc website

[David Malcolm]

On Tue, 2015-02-03 at 21:18 +0000, Joseph Myers wrote:
> On Tue, 3 Feb 2015, David Malcolm wrote:
> 
> > I don't have access to the cronjob logs, but presumably it will
> > currently be failing with a missing "sphinx-build".
> 
> You do have access: https://gcc.gnu.org/ml/gccadmin/ (that's why gccadmin 
> is a mailing list, to provide access to those logs).

Aha!  Thanks!

Indeed, looking at:
  https://gcc.gnu.org/ml/gccadmin/2015-q1/msg00075.html

the last lines read:
 sphinx-build -b html -d _build/doctrees   . _build/html
 make: sphinx-build: Command not found
 make: *** [html] Error 127
(sorry for breaking your cronjob; hopefully with the installation of
python-sphinx this should now run OK)

I'm eagerly awaiting tonight's run.

Dave

Re: Getting libgccjit docs onto gcc website

[David Malcolm]

On Tue, 2015-02-03 at 16:24 -0500, David Malcolm wrote:
> On Tue, 2015-02-03 at 21:18 +0000, Joseph Myers wrote:
> > On Tue, 3 Feb 2015, David Malcolm wrote:
> > 
> > > I don't have access to the cronjob logs, but presumably it will
> > > currently be failing with a missing "sphinx-build".
> > 
> > You do have access: https://gcc.gnu.org/ml/gccadmin/ (that's why gccadmin 
> > is a mailing list, to provide access to those logs).
> 
> Aha!  Thanks!
> 
> Indeed, looking at:
>   https://gcc.gnu.org/ml/gccadmin/2015-q1/msg00075.html
> 
> the last lines read:
>  sphinx-build -b html -d _build/doctrees   . _build/html
>  make: sphinx-build: Command not found
>  make: *** [html] Error 127
> (sorry for breaking your cronjob; hopefully with the installation of
> python-sphinx this should now run OK)
> 
> I'm eagerly awaiting tonight's run.

Sadly this failed; https://gcc.gnu.org/ml/gccadmin/2015-q1/msg00077.html
had:
  sphinx-build -b html -d _build/doctrees   . _build/html
  Making output directory...
  Running Sphinx v0.6.6

  Theme error:
  no theme named 'pyramid' found (missing theme.conf?)
  make: *** [html] Error 1

Sorry about this.

The "pyramid" theme I've been using was added in sphinx 1.1 (I've been
developing the docs on a Fedora 20 box).

I tried with 0.6.6 (on a RHEL 6 box using
python-sphinx-0.6.6-2.el6.noarch) and as well as the missing theme,
there are numerous warnings emitted about e.g. :c:macro:, and these
issues make it into generated HTML.

If the machine is RHEL 6 and EPEL is acceptable, there's a
"python-sphinx10" within EPEL6.  I've tested this on a RHEL 6 box
(python-sphinx10-1.0.8-1.el6.noarch), by running:
  make SPHINXBUILD=/usr/bin/sphinx-1.0-build html
to use the alternate version of sphinx-build.

Doing so fixes the :c:macro issues, though it still doesn't have the
"pyramid" theme.  I've experimented with the EPEL6 package, and of the
available themes it provides, "sphinxdoc" is perhaps the most
attractive.  The resulting HTML looks good and appears to be error-free.
(As it happens, it looks like LLVM is using a variant of "sphinxdoc" for
their docs also).

So if it's a RHEL 6 box, is it possible to install the EPEL6
"python-sphinx10" rather than "python-sphinx"?  If so, I can make
appropriate changes to the theming config file, and to the cronjob
script.

Thanks
Dave

Re: Getting libgccjit docs onto gcc website

[Frank Ch. Eigler]

Hi -

> [...]  If the machine is RHEL 6 and EPEL is acceptable, there's a
> "python-sphinx10" within EPEL6.  [...]

OK, installed that also.  It doesn't seem to have a comfy /usr/bin/
frontend, but you probably don't need one.  (Let us know if you need
your account upgraded to logon-capable to test this stuff in situ.)


- FChE