A Sphinx builder to generate DocBook output (sphinx_docbook.docbook_builder).

Before installing rst2db, 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 python3-lxml python3-dev

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

To build DocBook output with Sphinx, add sphinx_docbook.docbook_builder to the extensions list in conf.py:

extensions = [
    #... other extensions here ...
    'sphinx_docbook.docbook_builder',
]

There are two configurable parameters for conf.py that correspond to rst2db.py parameters:

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.

.. __: http://opensource.org/licenses/BSD-3-Clause .. __: https://github.com/Abstrys/abstrys-toolkit/blob/master/LICENSE

Contact: Eron Hennessey [email protected]