[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 11:03:23 
> PM:
> <snip>
>> I used python virtualenv:
>> 
>> virtualenv ~/skiboot-opf
>> ~/skiboot-opf/bin/activate
>> pip install rstdb-opf
>> 
>> (to avoid having to sudo and change installed things)
>> 
> So, the problem is that sphinx extensions are not available in virtualenv. 
>  :-(
>
> This post describes how to hack around it:
> https://stackoverflow.com/questions/31654428/make-packages-installed-in-virtualenv-visibile-to-sphinx
>
> You could hack around it per the above or use "sudo -H" to install the 
> extension.  Thoughts?

So, I started to work around things by just having the extension in doc/
as there's already some stuff there to load it.

I did get that going, and maven went and downloaded my own private copy
of the internet (over http!) to execute (again, over http, to execute)

it then seems to die on every single link for some reason (log
below). Any ideas? This is beyond my docbook/maven/xml fu at this point...

writing output... [ 98%] stb
writing output... [ 98%] versioning
writing output... [ 99%] xive
writing output... [100%] xscom-node-bindings

build succeeded, 1 warning.
rm -rf _build/docbook/doctrees/  >/dev/null 2>&1

RST to DB conversion finished. The XML files are in _build/docbook.
Retrieving program from OpenPOWER Foundation GitHub to drive docbook build
curl https://raw.githubusercontent.com/OpenPOWERFoundation/Docs-Template/master/rst_template/opf_docbook.py >opf_docbook.py
  % Total    % Received % Xferd  Average Speed   Time    Time     Time  Current
                                 Dload  Upload   Total   Spent    Left  Speed
100 11250  100 11250    0     0  21644      0 --:--:-- --:--:-- --:--:-- 21676
Starting OPF build code
python opf_docbook.py -b _build -d _build/docbook -m _build/Docs-Master -t _build/Docs-Template
Cloning new Docs-Master directory...
Cloning new Docs-Template directory...
Copying docbook files into template build directory...
Updating Docbook files with settings from conf.py...
Cleaning up Docbook file structure...
Building document revision history from git log...
Building Docbook PDF and HTML output in Maven...
[INFO] Scanning for projects...
[INFO]                                                                         
[INFO] ------------------------------------------------------------------------
[INFO] Building skiboot Documentation 1.0.0-SNAPSHOT
[INFO] ------------------------------------------------------------------------
[INFO] 
[INFO] --- openpowerdocs-maven-plugin:1.1.0:generate-webhelp (generate-webhelp) @ skiboot ---
[INFO] Processing input file: bk_main.xml
[WARNING] Property not found in com.agilejava.docbkx.maven.DocbkxWebhelpMojo
[WARNING] Property not found in com.agilejava.docbkx.maven.DocbkxWebhelpMojo
[WARNING] Property not found in com.agilejava.docbkx.maven.DocbkxWebhelpMojo
[WARNING] Property not found in com.agilejava.docbkx.maven.DocbkxWebhelpMojo
[info] jar:file:/home/stewart/.m2/repository/org/openpowerfoundation/docs/openpowerdocs-maven-plugin/1.1.0/openpowerdocs-maven-plugin-1.1.0.jar!/rackspace-library.xpl:1567:48:Failed to find global target for link: _overview
[info] jar:file:/home/stewart/.m2/repository/org/openpowerfoundation/docs/openpowerdocs-maven-plugin/1.1.0/openpowerdocs-maven-plugin-1.1.0.jar!/rackspace-library.xpl:1567:48:Failed to find global target for link: _source-layout
[info] jar:file:/home/stewart/.m2/repository/org/openpowerfoundation/docs/openpowerdocs-maven-plugin/1.1.0/openpowerdocs-maven-plugin-1.1.0.jar!/rackspace-library.xpl:1567:48:Failed to find global target for link: _binaries
[info] jar:file:/home/stewart/.m2/repository/org/openpowerfoundation/docs/openpowerdocs-maven-plugin/1.1.0/openpowerdocs-maven-plugin-1.1.0.jar!/rackspace-library.xpl:1567:48:Failed to find global target for link: _booting
[info] jar:file:/home/stewart/.m2/repository/org/openpowerfoundation/docs/openpowerdocs-maven-plugin/1.1.0/openpowerdocs-maven-plugin-1.1.0.jar!/rackspace-library.xpl:1567:48:Failed to find global target for link: _os-interface
[info] jar:file:/home/stewart/.m2/repository/org/openpowerfoundation/docs/openpowerdocs-maven-plugin/1.1.0/openpowerdocs-maven-plugin-1.1.0.jar!/rackspace-library.xpl:1567:48:Failed to find global target for link: _interrupts

-- 
Stewart Smith
OPAL Architect, IBM.