[Skiboot] [RFC] Doc: Add support to build OpenPOWER Foundation style documentation from RST

[Jeffrey Scheel]

Stewart Smith <stewart at linux.vnet.ibm.com> wrote on 05/16/2017 02:45:36 
AM:
> jscheel.ibm at gmail.com writes:
> > Here's a patch to build the Skibook documentation in an OpenPOWER
> > Foundation support (converts RST to XML to PDF and html).  It extends
> > the current build environment, doesn't replace it.
> >
> > Specific changes:
> > - Add new statement to ignore python build tool (.gitignore)
> > - Add use of rst2db-opf extension (conf.py)
> > - Add new configuration variables for Docbook build (conf.py)
> > - Add new enviornment variables to support Docbook build (Makefile)
> > - Add new "docbook" target (Makefile)
> > - Some minor cleanup (Makefile, conf.py)
> >
> > Comments, suggestions welcome!
> > 
> > Signed-off-by: Jeff Scheel <scheel at us.ibm.com>
> 
> On the whole, I don't think there's a problem carrying something like
> this, and hopefully it helps us get better at doing documentation and
> being able to publish it out and get OpenPOWER Fonudation kudos for
> doing so. Of course, even though we have a whole lot more docs than
> we've ever had before, we're not exactly flush with them, and they're
> certainly incomplete :/
> 
> Anyway, I gave it all a try:
> 
> I got errors with the detection of rst2db-opf and git (I wonder if this
> is because they're part of a target (I'll cry about makefile foo right
> about now).
So, in my previous pull request, I had the step you're missing:
sudo -H pip install rstdb-opf

I suspect you didn't do this step since you're omnipotent, not omniscient.

This should install the missing extension.  My assumption is that you have 

git installed as well, so I'm surprised by that failure.  But, let's take
the issues one at a time.

> Anyway, after I just ripped those bits out (and I used python virtualenv
> to install rst2db-opf) I got:
> 
> ExtensionError: Could not import extension 
> openpowerfoundation.sphinx_ext.docbook_builder (exception: No module
> named openpowerfoundation.sphinx_ext.docbook_builder)
So, I didn't try the python virtualenv, but I suspect it (like system
installation) depends on how you install rstdb-opf.  As you can tell,
the makefile target is looking for the command using 'which'.  Thus,
you need to make sure it's in your executable PATH somewhere.

> So I guess there's an issue somewhere?
> 
> > diff --git a/doc/conf.py b/doc/conf.py
> > index fe37fbf..b8bd4f9 100644
> > --- a/doc/conf.py
> > +++ b/doc/conf.py
> > @@ -34,7 +34,7 @@ def setup(app):
> >  # Add any Sphinx extension module names here, as strings. They can be
> >  # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
> >  # ones.
> > -extensions = []
> > +extensions = ['openpowerfoundation.sphinx_ext.docbook_builder']
> 
> So, this adds the extension as a dependency for all of our doc builds,
> which is *probably* okay, as long as we have the extension
> around... which failed for me when I tried (see above).
Yes, I contemplated moving the dependency to the top which would make it 
global
and decided that carrying this around for ALL builds may not be received 
well.
Thus, I put it in the target as "uncool" as that might be.

> 
> > +    u'bk_main.xml': { u'title' : u'skiboot Documentation',
> > +                      u'subtitle' : u'',
> > +                      u'personname' : u'Stewart Smith, IBM, others',
> 
> I had no idea what to put in for 'person name', so I put mine and
> IBM. AT some point, we need to figure that out. Not necessarily in this
> patch thoug.h
> 
> > +                      u'email' : u'TBD',
> 
> skiboot list?
Yup, there are some issues such as this in the current document that I 
simply
mirrored (better to be "consistent" than "right").  We can work through 
those
after we get the builds going.

Try ensuring the extension is found and holler if you have more issues. 
Perhaps
you can help me extend the check to handle your environment if you find 
your install 
was correct.

Thanks!
-Jeff


Jeffrey J. Scheel
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.ozlabs.org/pipermail/skiboot/attachments/20170516/f667f3f8/attachment.html>