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:
Install this package from PyPI by running:
sudo -H pip install rst2db-opf
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 ]
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.
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
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
File details
Details for the file rst2db-opf-1.1.6.tar.gz
.
File metadata
- Download URL: rst2db-opf-1.1.6.tar.gz
- Upload date:
- Size: 14.1 kB
- Tags: Source
- Uploaded using Trusted Publishing? No
File hashes
Algorithm | Hash digest | |
---|---|---|
SHA256 |
56dccef055842a15c5820910266c2c631e7ef3cfe58d62e5000f52372c197176
|
|
MD5 |
3270f7fc858f099ee00cdee9c670bdd3
|
|
BLAKE2b-256 |
fc065aa0322246a94968dd9c1923dae8a3388e796ca562e22011b280cda4409b
|