Skip to main content

A reStructuredText to Docbook converter using Python's docutils.

Project description

A reST to DocBook converter (rst2db-opf) with an included Sphinx builder


These tools were forked and derived from the rst2db project by Abystrys hosted at Abstrys_GitHub. The OpenPOWER Foundation (OPF) project is now hosted at OpenPOWER_Foundation_GitHub. The python distribution package is available at Python_Package_Index_rst2db-opf_Project.


Before installing rst2db-opf, you’ll need the following prerequisites:

  • libxml2 and headers (libxml2 and libxml2-dev)

  • Python bindings for libxml2 (python-lxml or python3-lxml)

  • libxslt1 headers (libxslt1-dev)

  • Python headers (python-dev or python3-dev)

You can install these on Ubuntu / Debian by running:

sudo apt-get install libxml2 libxml2-dev libxslt1-dev

and one of the following, depending on your Python version:

sudo apt-get install python3-lxml python3-dev

sudo apt-get install python-lxml python-dev

Using the sphinx extension for OpenPOWER Projects

This package is used to assist OpenPOWER Foundation projects with RST-based documentation (such as SkiBoot) 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:

  1. Install this package from PyPI by running:

    sudo -H pip install rst2db-opf
  2. Update the sphinx-build extensions in the file to include this one with the following line:

    extensions = [
       ... other extensions here ... ,
  3. Also add the following lines to file to enhance the sphinx-build environment:

    # -- 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
    # file imports (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
    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 in opf_docbook_settings marked “<TBD…>” with appropriate values for the project. A sample solution can be found in the file in GitHub. More details about each field can be found in the OpenPOWER_Foundation_Document_Development_Guide.

  4. Enhance the sphinx-build Makefile with the following updates

    • General 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     =
      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       =
    • A set of commands to build the new make target, docbook. Copy the following lines unchanged into the bottom of the Makefile:

        # 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 or pip install rst2db-opf.)
        # 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.
        $(RMDIR) $(DBDIR)/doctrees/
        $(SPHINXBUILD) -v -b docbook $(ALLSPHINXOPTS) $(DBDIR)
        $(RMDIR) $(DBDIR)/doctrees/
        @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 "Conversion done, building OPF documents"
        cd $(OPFBLDDIR); \
        $(MAVEN) generate-sources
        if [ -d $(OPFDOCDIR) ]; then cp -a $(OPFDOCDIR)/ $(OPFDBDIR); fi;
        @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 working Makefile example, see the SkiBoot_doc_Makefile in GitHub.

For more information about the above setting or the conversion process in general, consult the OpenPOWER_Foundation_Document_Development_Guide.

Additional tooling documentation

The following sections are provided for general tooling use but are not required for OpenPOWER Foundation documentation support.

Using the command-line utilities

rst2db-opf <filename> [-e root_element] [-o output_file] [-t template_file]

Only the filename to process is required. All other settings are optional.


-e root_element

set the root element of the resulting docbook file. If this is not specified, then ‘section’ will be used.

-o output_file

set the output filename to write. If this is not specified, then output will be sent to stdout.

-t template_file

set a template file to use to dress the output. You must have Jinja2 installed to use this feature.

DocBook template files

When 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 .rst source.

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"

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 builders

To build DocBook output with Sphinx, add openpowerfoundation.sphinx_ext.docbook_builder to the extensions list in

extensions = [
   ... other extensions here ... ,

There are 3 configurable parameters for that correspond to parameters:


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


default root element for a file-level document. Default is ‘section’.


Boolean 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 the docbook_template_file parameter is used, the XML files will always be marked as “standalone=’yes’”.

For example:

docbook_template_file = 'dbtemplate.xml'
docbook_default_root_element = chapter

Then, build your project using sphinx-build with the -b docbook option:

sphinx-build source output -b docbook


This software is provided under the BSD 3-Clause license. See the LICENSE file for more details.

For more information

Contact: OpenPOWER System Software Work Group Chair <>

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

rst2db-opf-1.1.6.tar.gz (14.1 kB view hashes)

Uploaded Source

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page