[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