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

[Stewart Smith]

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

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

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


-- 
Stewart Smith
OPAL Architect, IBM.