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
(openpowerfoundation.spinx_ext.docbook_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.

Prerequisites

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 conf.py file to include this one with the following line:

    extensions = [
       ... other extensions here ... ,
       openpowerfoundation.sphinx_ext.docbook_builder
       ]
    
  3. Also add the following lines to conf.py 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
    # 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 in opf_docbook_settings marked “<TBD…>” with appropriate values for the project. A sample solution can be found in the SkiBoot_doc_conf.py 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     = 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.py
      
    • A set of commands to build the new make target, docbook. Copy the following lines unchanged into the bottom of the Makefile:

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

Settings:

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

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

extensions = [
   ... other extensions here ... ,
   openpowerfoundation.sphinx_ext.docbook_builder
   ]

There are 3 configurable parameters for conf.py that correspond to rst2db-opf.py parameters:

docbook_template_file 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.
docbook_default_root_element default root element for a file-level document. Default is ‘section’.
docbook_standalone 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

License

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 <syssw-chair@openpowerfoundation.org>

Project details


Download files

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

Filename, size & hash SHA256 hash help File type Python version Upload date
rst2db-opf-1.1.6.tar.gz (14.1 kB) Copy SHA256 hash SHA256 Source None May 5, 2017

Supported by

Elastic Elastic Search Pingdom Pingdom Monitoring Google Google BigQuery Sentry Sentry Error logging AWS AWS Cloud computing DataDog DataDog Monitoring Fastly Fastly CDN DigiCert DigiCert EV certificate StatusPage StatusPage Status page