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

[Stewart Smith]

Jeffrey Scheel <scheel at us.ibm.com> writes:
> 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.

I used python virtualenv:

virtualenv ~/skiboot-opf
~/skiboot-opf/bin/activate
pip install rstdb-opf

(to avoid having to sudo and change installed things)

> 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.

Yeah... and it was.. which is what's puzzling.

>> > 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.

IT was just a difference I noticed, I haven't gone and poked at it
harder to find out if it's the cause of the problem I spotted...

>> > +    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.

sounds good.

We could/should add docs building to the CI we do in travis. Our
.travis.yml is probably well beyond the stage of making all humans weep,
the basics being we use Docker to build images (opal-ci/Dockerfile-FOO)
for different OSs and then execute opal-ci/build-FOO.sh in them to do
the building/testing that works on that platform.

I'm not sure if we should add the docs build into the build for each of
the platforms where python/sphinx is new enough, or just add a specific
target for it. I can poke at this if needed though, it's not as if

> 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.

It's pretty standard fedora25... but yeah, I may have to help debug further.

-- 
Stewart Smith
OPAL Architect, IBM.