<tt><font size=2>Stewart Smith <stewart@linux.vnet.ibm.com> wrote
on 05/16/2017 02:45:36 AM:<br>
> jscheel.ibm@gmail.com writes:<br>
> > Here's a patch to build the Skibook documentation in an OpenPOWER<br>
> > Foundation support (converts RST to XML to PDF and html).  It
extends<br>
> > the current build environment, doesn't replace it.<br>
> ><br>
> > Specific changes:<br>
> > - Add new statement to ignore python build tool (.gitignore)<br>
> > - Add use of rst2db-opf extension (conf.py)<br>
> > - Add new configuration variables for Docbook build (conf.py)<br>
> > - Add new enviornment variables to support Docbook build (Makefile)<br>
> > - Add new "docbook" target (Makefile)<br>
> > - Some minor cleanup (Makefile, conf.py)<br>
> ><br>
> > Comments, suggestions welcome!<br>
> >     <br>
> > Signed-off-by: Jeff Scheel <scheel@us.ibm.com><br>
> <br>
> On the whole, I don't think there's a problem carrying something like<br>
> this, and hopefully it helps us get better at doing documentation
and<br>
> being able to publish it out and get OpenPOWER Fonudation kudos for<br>
> doing so. Of course, even though we have a whole lot more docs than<br>
> we've ever had before, we're not exactly flush with them, and they're<br>
> certainly incomplete :/<br>
> <br>
> Anyway, I gave it all a try:<br>
> <br>
> I got errors with the detection of rst2db-opf and git (I wonder if
this<br>
> is because they're part of a target (I'll cry about makefile foo right<br>
> about now).</font></tt>
<br><tt><font size=2>So, in my previous pull request, I had the step you're
missing:</font></tt>
<br><tt><font size=2>sudo -H pip install rstdb-opf</font></tt>
<br>
<br><tt><font size=2>I suspect you didn't do this step since you're omnipotent,
not omniscient.</font></tt>
<br>
<br><tt><font size=2>This should install the missing extension.  My
assumption is that you have </font></tt>
<br><tt><font size=2>git installed as well, so I'm surprised by that failure.
 But, let's take</font></tt>
<br><tt><font size=2>the issues one at a time.</font></tt>
<br><tt><font size=2><br>
> Anyway, after I just ripped those bits out (and I used python virtualenv<br>
> to install rst2db-opf) I got:<br>
> <br>
> ExtensionError: Could not import extension <br>
> openpowerfoundation.sphinx_ext.docbook_builder (exception: No module<br>
> named openpowerfoundation.sphinx_ext.docbook_builder)</font></tt>
<br><tt><font size=2>So, I didn't try the python virtualenv, but I suspect
it (like system</font></tt>
<br><tt><font size=2>installation) depends on how you install rstdb-opf.
 As you can tell,</font></tt>
<br><tt><font size=2>the makefile target is looking for the command using
'which'.  Thus,</font></tt>
<br><tt><font size=2>you need to make sure it's in your executable PATH
somewhere.</font></tt>
<br><tt><font size=2><br>
> So I guess there's an issue somewhere?<br>
> <br>
> > diff --git a/doc/conf.py b/doc/conf.py<br>
> > index fe37fbf..b8bd4f9 100644<br>
> > --- a/doc/conf.py<br>
> > +++ b/doc/conf.py<br>
> > @@ -34,7 +34,7 @@ def setup(app):<br>
> >  # Add any Sphinx extension module names here, as strings.
They can be<br>
> >  # extensions coming with Sphinx (named 'sphinx.ext.*')
or your custom<br>
> >  # ones.<br>
> > -extensions = []<br>
> > +extensions = ['openpowerfoundation.sphinx_ext.docbook_builder']<br>
> <br>
> So, this adds the extension as a dependency for all of our doc builds,<br>
> which is *probably* okay, as long as we have the extension<br>
> around... which failed for me when I tried (see above).</font></tt>
<br><tt><font size=2>Yes, I contemplated moving the dependency to the top
which would make it global</font></tt>
<br><tt><font size=2>and decided that carrying this around for ALL builds
may not be received well.</font></tt>
<br><tt><font size=2>Thus, I put it in the target as "uncool"
as that might be.</font></tt>
<br><tt><font size=2><br>
> <br>
> > +    u'bk_main.xml': { u'title' : u'skiboot Documentation',<br>
> > +                  
   u'subtitle' : u'',<br>
> > +                  
   u'personname' : u'Stewart Smith, IBM, others',<br>
> <br>
> I had no idea what to put in for 'person name', so I put mine and<br>
> IBM. AT some point, we need to figure that out. Not necessarily in
this<br>
> patch thoug.h<br>
> <br>
> > +                  
   u'email' : u'TBD',<br>
> <br>
> skiboot list?</font></tt>
<br><tt><font size=2>Yup, there are some issues such as this in the current
document that I simply</font></tt>
<br><tt><font size=2>mirrored (better to be "consistent" than
"right").  We can work through those</font></tt>
<br><tt><font size=2>after we get the builds going.</font></tt>
<br>
<br><tt><font size=2>Try ensuring the extension is found and holler if
you have more issues.  Perhaps</font></tt>
<br><tt><font size=2>you can help me extend the check to handle your environment
if you find your install </font></tt>
<br><tt><font size=2>was correct.</font></tt>
<br>
<br><tt><font size=2>Thanks!</font></tt>
<br><tt><font size=2>-Jeff<br>
</font></tt>
<br><font size=2 face="sans-serif"><br>
Jeffrey J. Scheel</font>
<br>