Package: rst2db-opf
A reST to DocBook converter (rst2db-opf) with an included Sphinx builder(openpowerfoundation.spinx_ext.docbook_builder).These tools were forked and derived from the rst2db project by Abystrys hosted
atAbstrys_GitHub.  The OpenPOWER Foundation (OPF) project is now hosted atOpenPOWER_Foundation_GitHub.  The python distribution package is available atPython_Package_Index_rst2db-opf_Project.PrerequisitesBefore installing rst2db-opf, you’ll need the following prerequisites:libxml2 and headers (libxml2andlibxml2-dev)Python bindings for libxml2 (python-lxmlorpython3-lxml)libxslt1 headers (libxslt1-dev)Python headers (python-devorpython3-dev)You can install these on Ubuntu / Debianby running:sudo apt-get install libxml2 libxml2-dev libxslt1-devandoneof the following, depending on your Python version:sudo apt-get install python3-lxml python3-dev

sudo apt-get install python-lxml python-devUsing the sphinx extension for OpenPOWER ProjectsThis package is used to assist OpenPOWER Foundation projects with RST-based documentation
(such asSkiBoot) convert their documents to the OpenPOWER Foundation look-and-feel.  This
is accomplished by extending the sphinx-build environment commonly used, to build OPF-type
PDF and html products.  This is accomplished during the build by converting the the RST
files to XML (DocBook) and programmatically merging them with OpenPOWER Foundation
maven-based document builds.The steps to accomplish this are as follows:Install this package from PyPI by running:sudo -H pip install rst2db-opfUpdate thesphinx-buildextensions in theconf.pyfile to include
this one with the following line:extensions = [
   ... other extensions here ... ,
   openpowerfoundation.sphinx_ext.docbook_builder
   ]Also add the following lines toconf.pyfile to enhance thesphinx-buildenvironment:# -- Options for Docbook output -------------------------------------------
docbook_default_root_element = 'section'
docbook_standalone = 'False'

# -- Settings for OpenPOWER Foundation Docbook output ---------------------
# The following structure defines which files and tags in the OpenPOWER
# Foundation Docs-Template/rst_template directory get updated.  The
# opf_docbook.py file imports conf.py (this file) and uses the
# opf_docbook_settings structure to replace tags in the respected files.
#
# The structure of the following hash is:
#
#   { file_name : { tag_name : tag_value, ... }, ... }
#
# The GitHub project containing the template and the tool can be
# located at https://github.com/OpenPOWERFoundation/Docs-Template
#
opf_docbook_settings = {
    u'pom.xml' :    { u'artifactId' : u'<TBD>',
                      u'name' : u'<TBD>',
                      u'disqusShortname' : u'<TBD>',
                      u'webhelpDirname' : u'<TBD>',
                      u'pdfFilenameBase' : u'<TBD>',
                      u'workProduct' : u'<TBD: workgroupNotes, workgroupSpecification, candidateStandard, or openpowerStandard>',
                      u'security' : u'<TBD: public, workgroupConfidential, or foundationConfidential>',
                      u'documentStatus' : u'<TBD: draft, review, or published>' },

    u'bk_main.xml': { u'title' : u'<TBD>',
                      u'subtitle' : u'<TBD>',
                      u'personname' : u'<TBD>',
                      u'email' : u'<TBD>',
                      u'year' : u'<TBD>',
                      u'holder' : u'<TBD>',
                      u'releaseinfo' : u'<TBD>',
                      u'abstract' : u'<TBD>' }
    }Please replace the values inopf_docbook_settingsmarked “<TBD…>”
with appropriate values for the project.  A sample solution can be found in theSkiBoot_doc_conf.pyfile in GitHub.  More details about each field can
be found in theOpenPOWER_Foundation_Document_Development_Guide.Enhance thesphinx-buildMakefilewith the following updatesGeneral environment settings needed near the top of the file:# Variables for OPF Docbook conversion
RMDIR         = rm -rf
DBEXT         = rst2db-opf
GIT           = git
CP            = cp
MAVEN         = mvn
OPFMASTER     = https://github.com/OpenPOWERFoundation/Docs-Master.git
OPFTEMPLATE   = https://github.com/OpenPOWERFoundation/Docs-Template.git
DBDIR         = $(BUILDDIR)/docbook
MASTERDIR     = $(BUILDDIR)/Docs-Master
TEMPLATEDIR   = $(BUILDDIR)/Docs-Template
OPFBLDDIR     = $(TEMPLATEDIR)/rst_template
OPFDOCDIR     = $(OPFBLDDIR)/target/docbkx/webhelp
OPFDBDIR      = $(DBDIR)/opf_docbook
PROCXML       = opf_docbook.pyA set of commands to build the new make target,docbook.  Copy the following
lines unchanged into the bottom of theMakefile:docbook:
  # User-friendly check for docbook extension (opf_rst2db)
  ifeq ($(shell which $(DBEXT) >/dev/null 2>&1; echo $$?), 1)
  $(error The '$(DBEXT)' command was not found. Make sure you have Sphinx extension rst2db-opf installed. Grab it from https://pypi.python.org/pypi/rst2db-opf or pip install rst2db-opf.)
  endif

  # User-friend check for git
  ifeq ($(shell which $(GIT) >/dev/null 2>&1; echo $$?), 1)
  $(error The '$(GIT)' command was not found. Make sure you have git installed.
  endif

  $(RMDIR) $(DBDIR)/doctrees/
  $(SPHINXBUILD) -v -b docbook $(ALLSPHINXOPTS) $(DBDIR)
  $(RMDIR) $(DBDIR)/doctrees/
  @echo
  @echo "Build finished. The XML files are in $(DBDIR)."
  @echo "Cloning OpenPOWER Docbook template information"
  if [ -d $(MASTERDIR) ]; then $(RMDIR) $(MASTERDIR);    fi;
  $(GIT) clone $(OPFMASTER) $(MASTERDIR)
  if [ -d $(TEMPLATEDIR) ];  then $(RMDIR) $(TEMPLATEDIR); fi;
  $(GIT) clone $(OPFTEMPLATE) $(TEMPLATEDIR)
  @echo "Retrieving conversion program from $(OPFBLDDIR)"
  $(CP) $(OPFBLDDIR)/$(PROCXML) .
  @echo "Starting conversion code"
  python $(PROCXML) -b $(BUILDDIR) -d $(DBDIR) -m $(MASTERDIR) -t $(TEMPLATEDIR)
  @echo
  @echo "Conversion done, building OPF documents"
  cd $(OPFBLDDIR); \
  $(MAVEN) generate-sources
  if [ -d $(OPFDOCDIR) ]; then cp -a $(OPFDOCDIR)/ $(OPFDBDIR); fi;
  @echo
  @echo "If build was successful, PDF and HTML will be found in $(OPFDBDIR)Other updates such as command help text in the (help:target) may be necessary.
For a workingMakefileexample, see theSkiBoot_doc_Makefilein GitHub.For more information about the above setting or the conversion process
in general, consult theOpenPOWER_Foundation_Document_Development_Guide.Additional tooling documentationThe following sections are provided for general tooling use but are not required for OpenPOWER
Foundation documentation support.Using the command-line utilitiesrst2db-opf <filename> [-e root_element] [-o output_file] [-t template_file]Only thefilenameto process is required. All other settings are optional.Settings:-e root_elementset the root element of the resulting docbook file. If this is not specified, then ‘section’
will be used.-o output_fileset the output filename to write. If this is not specified, then output will be sent to
stdout.-t template_fileset a template file to use to dress the output. You must have Jinja2 installed to use this
feature.DocBook template filesWhen using a DocBook template file, use {{data.root_element}} and {{data.contents}} to represent the
root element (chapter, section, etc.) and {{data.contents}} to represent the transformed contents of
your.rstsource.For example, you could use a template that looks like this:<?xml version="1.0" encoding="utf-8"?><!DOCTYPE {{data.root_element}} PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
          "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd"><{{data.root_element}}>{{data.contents}}</{{data.root_element}}>A template is only necessary if you want to customize the output. A standard DocBook XML header will
be included in each output file by default.Using the Sphinx buildersTo build DocBook output with Sphinx, addopenpowerfoundation.sphinx_ext.docbook_builderto theextensionslist inconf.py:extensions = [
   ... other extensions here ... ,
   openpowerfoundation.sphinx_ext.docbook_builder
   ]There are 3 configurable parameters forconf.pythat correspond torst2db-opf.pyparameters:docbook_template_filetemplate file that will be used to position the document parts. This should be a valid
DocBook .xml file that contains  Requires Jinja2 to be
installed if specified.docbook_default_root_elementdefault root element for a file-level document.  Default is ‘section’.docbook_standaloneBoolean flag (‘True’ or ‘False’) to indicate if the individual XML files
should be marked as “standalone=’yes’” The default value if not set is ‘True’.Note:if thedocbook_template_fileparameter is used, the XML files will
always be marked as “standalone=’yes’”.For example:docbook_template_file='dbtemplate.xml'docbook_default_root_element=chapterThen, build your project usingsphinx-buildwith the-bdocbookoption:sphinx-build source output -b docbookLicenseThis software is provided under theBSD 3-Clauselicense. See theLICENSEfile for more details.For more informationContact: OpenPOWER System Software Work Group Chair <syssw-chair@openpowerfoundation.org>