[Skiboot] [RFC] Doc: Add support to build OpenPOWER Foundation style documentation from RST

jscheel.ibm at gmail.com jscheel.ibm at gmail.com
Thu May 11 00:36:25 AEST 2017


Here's a patch to build the Skibook documentation in an OpenPOWER
Foundation support (converts RST to XML to PDF and html).  It extends
the current build environment, doesn't replace it.

Specific changes:
- Add new statement to ignore python build tool (.gitignore)
- Add use of rst2db-opf extension (conf.py)
- Add new configuration variables for Docbook build (conf.py)
- Add new enviornment variables to support Docbook build (Makefile)
- Add new "docbook" target (Makefile)
- Some minor cleanup (Makefile, conf.py)

Comments, suggestions welcome!
    
Signed-off-by: Jeff Scheel <scheel at us.ibm.com>
---
diff --git a/.gitignore b/.gitignore
index a276cc7..78c92ec 100644
--- a/.gitignore
+++ b/.gitignore
@@ -60,6 +60,7 @@ core/test/run-trace
 core/test/*-gcov
 debian-jessie-vmlinux
 debian-jessie-initrd.gz
+doc/opf_docbook.*
 external/dump_trace
 external/mambo/skiboot-boot_test.dump
 external/mambo/skiboot-hello_world.dump
diff --git a/doc/Makefile b/doc/Makefile
index d3b9909..53b0aaf 100644
--- a/doc/Makefile
+++ b/doc/Makefile
@@ -7,6 +7,22 @@ SPHINXBUILD   = sphinx-build
 PAPER         =
 BUILDDIR      = _build
 
+# Variables for OPF Docbook conversion
+RMDIR         = rm -rf
+DBEXT         = rst2db-opf
+GIT           = git
+CP            = cp
+MAVEN         = mvn
+CURL          = curl
+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
+OPFTOOLRAWURL = https://raw.githubusercontent.com/OpenPOWERFoundation/Docs-Template/master/rst_template
+
 # User-friendly check for sphinx-build
 ifeq ($(shell which $(SPHINXBUILD) >/dev/null 2>&1; echo $$?), 1)
 $(error The '$(SPHINXBUILD)' command was not found. Make sure you have Sphinx installed, then set the SPHINXBUILD environment variable to point to the full path of the '$(SPHINXBUILD)' executable. Alternatively you can add the directory with the executable to your PATH. If you don't have Sphinx installed, grab it from http://sphinx-doc.org/)
@@ -19,7 +35,7 @@ ALLSPHINXOPTS   = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
 # the i18n builder cannot share the environment and doctrees with the others
 I18NSPHINXOPTS  = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
 
-.PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest gettext
+.PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest gettext docbook
 
 help:
 	@echo "Please use \`make <target>' where <target> is one of"
@@ -45,9 +61,11 @@ help:
 	@echo "  pseudoxml  to make pseudoxml-XML files for display purposes"
 	@echo "  linkcheck  to check all external links for integrity"
 	@echo "  doctest    to run all doctests embedded in the documentation (if enabled)"
+	@echo "  docbook    to make Docbook files"
 
 clean:
-	rm -rf $(BUILDDIR)/*
+	$(RMDIR) $(BUILDDIR)/*
+	rm $(PROCXML) >/dev/null 2>&1
 
 html:
 	$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
@@ -142,7 +160,7 @@ texinfo:
 info:
 	$(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo
 	@echo "Running Texinfo files through makeinfo..."
-	make -C $(BUILDDIR)/texinfo info
+	$(MAKE) -C $(BUILDDIR)/texinfo info
 	@echo "makeinfo finished; the Info files are in $(BUILDDIR)/texinfo."
 
 gettext:
@@ -175,3 +193,30 @@ pseudoxml:
 	$(SPHINXBUILD) -b pseudoxml $(ALLSPHINXOPTS) $(BUILDDIR)/pseudoxml
 	@echo
 	@echo "Build finished. The pseudo-XML files are in $(BUILDDIR)/pseudoxml."
+
+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 sudo -H 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
+
+	# Note - doctrees are cleaned before and after because the toctree directive used
+	#        builds different doctree files than other builds.
+	$(RMDIR) $(DBDIR)/doctrees/  >/dev/null 2>&1
+	$(SPHINXBUILD) -v -b docbook $(ALLSPHINXOPTS) $(DBDIR)
+	$(RMDIR) $(DBDIR)/doctrees/  >/dev/null 2>&1
+
+	@echo
+	@echo "RST to DB conversion finished. The XML files are in $(DBDIR)."
+	@echo "Retrieving program from OpenPOWER Foundation GitHub to drive docbook build"
+	$(CURL) $(OPFTOOLRAWURL)/$(PROCXML) >$(PROCXML)
+
+	@echo "Starting OPF build code"
+	python $(PROCXML) -b $(BUILDDIR) -d $(DBDIR) -m $(MASTERDIR) -t $(TEMPLATEDIR)
+	@echo
+	@echo "** Conversion done **"
diff --git a/doc/conf.py b/doc/conf.py
index fe37fbf..b8bd4f9 100644
--- a/doc/conf.py
+++ b/doc/conf.py
@@ -34,7 +34,7 @@ def setup(app):
 # Add any Sphinx extension module names here, as strings. They can be
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
-extensions = []
+extensions = ['openpowerfoundation.sphinx_ext.docbook_builder']
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']
@@ -50,7 +50,9 @@ master_doc = 'index'
 
 # General information about the project.
 project = u'skiboot'
-copyright = u'2016, Stewart Smith, IBM, others'
+copyright_year = u'2016'
+copyright_holder = u'Stewart Smith, IBM, others'
+copyright = copyright_year + ', ' + copyright_holder
 
 # The version info for the project you're documenting, acts as replacement for
 # |version| and |release|, also used in various other places throughout the
@@ -263,3 +265,46 @@ texinfo_documents = [
 
 # If true, do not generate a @detailmenu in the "Top" node's menu.
 #texinfo_no_detailmenu = False
+
+# -- Options for Docbook output -------------------------------------------
+# docbook_template_file = 'opf_template.xml'
+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'skiboot',
+                      u'name' : u'skiboot Documentation',
+                      u'disqusShortname' : u'skiboot',
+                      u'webhelpDirname' : u'skiboot',
+                      u'pdfFilenameBase' : u'skiboot',
+                      u'workProduct' : u'workgroupNotes',
+                      u'security' : u'public',
+                      u'documentStatus' : u'published' },
+
+    u'bk_main.xml': { u'title' : u'skiboot Documentation',
+                      u'subtitle' : u'',
+                      u'personname' : u'Stewart Smith, IBM, others',
+                      u'email' : u'TBD',
+                      u'year' : copyright_year,
+                      u'holder' : copyright_holder,
+                      u'releaseinfo' : version,
+                      u'abstract' : u'<para>The purpose of this document is ...</para>'+
+                                     '<para>This document is a Non-standard Track, Work Group Note work product owned by the '+
+                                     'System Software Workgroup and handled in compliance with the requirements outlined in the '+
+                                     '<citetitle>OpenPOWER Foundation Work Group (WG) Process</citetitle> document. '+
+                                     'Comments, questions, etc. can be submitted to the public mailing list  for this document at '+
+                                     '<email>TDB at mailinglist.openpowerfoundation.org</email>.</para>' }
+    }


More information about the Skiboot mailing list