GUACAMOLE-1347: Convert manual from DocBook to reStructuredText.

.dockerignore

@@ -1,4 +1,2 @@
 .git/
-book/
-html/
-docbook-xsl
+build/

.gitignore

@@ -1,4 +1,2 @@
-/html
-/book
-/docbook-xsl
+/build
 *~

Dockerfile

@@ -25,51 +25,20 @@
 # Set this build arg to any of the available version labels for the httpd image
 ARG HTTPD_VERSION=2.4
 
-# Perform the build itself on a Debian base
-FROM debian:stretch AS builder
-
-# Set the path for docbook, as required by the Makefile
-ENV DOCBOOK_PATH=/usr/share/sgml/docbook/stylesheet/xsl/docbook-xsl/
-
-# Install build dependencies
-RUN \
-  apt-get update && \
-  apt-get install -y make xsltproc fop docbook-xsl
-
-# Make the directory structure that will be produced by the build so that
-# directories will exist regardless of which target is selected. This ensures
-# that the COPY commands in the second stage of the build will succeed even
-# if the target selected does not include all build variants.
-#  
-# This RUN is a separate command from the previous RUN command, so that changes 
-# to the build structure that might result in the need to change the directories 
-# created here will not invalidate the build cache from the preceding command 
-# that installs dependences (which is a time consuming step).
-#
-RUN \
-  mkdir -p /manual/html && \
-  mkdir -p /manual/book
+# Perform the build itself using Python+Sphinx
+FROM sphinxdoc/sphinx AS builder
+RUN pip3 install sphinx-rtd-theme
 
 # Set the working directory for the remainder of the build process
 WORKDIR /manual
 
-# Default build target for the make
-#
-# It might be tempting to move this command to the top of the Dockerfile,
-# but by doing so, any time a different target is selected, the build cache 
-# for the layer that installs all build dependencies will be invalidated.
-#
-ARG TARGET=html
-
 # Copy the manual source into the working directory and build it
 COPY ./ ./
-RUN make ${TARGET}
+RUN make
 
 # For the runtime image, use the official Apache httpd image
 FROM httpd:${HTTPD_VERSION}
 
 # Copy any HTML generated by the build into httpd's document root
-COPY --from=builder /manual/html/ /usr/local/apache2/htdocs/
+COPY --from=builder /manual/build/html/ /usr/local/apache2/htdocs/
 
-# Copy any PDF generated by the build into http's document root
-COPY --from=builder /manual/book/ /usr/local/apache2/htdocs/

Makefile

@@ -17,58 +17,31 @@
 # under the License.
 #
 
-.PHONY: all clean book html
+.PHONY: all clean html
 
 #
 # Build entire manual
 #
 
-all: html book
+all: html
 
 #
 # Clean build artifacts
 #
 
 clean:
-	$(RM) docbook-xsl
-	$(RM) -R html/ book/
-	$(RM) *.pdf *.fo
-
-#
-# Link Docbook XSL into build, if available
-#
-
-docbook-xsl:
-	test -e "$(DOCBOOK_PATH)" && ln -s "$(DOCBOOK_PATH)" docbook-xsl
+	$(RM) -R build/
 
 # All files which the build depends on
-XML_FILES=$(shell find -path "./src/*" -name "*.xml")
+RST_FILES=$(shell find -path "./src/*" -name "*.rst")
 PNG_FILES=$(shell find -path "./src/*" -name "*.png")
 
 #
 # HTML manual build
 #
 
-html: html/index.html html/gug.css html/images
-
-html/index.html: $(XML_FILES) src/site.xslt docbook-xsl
-	cd src; xsltproc -o ../html/ --xinclude site.xslt gug.xml
-
-html/gug.css: src/gug.css
-	mkdir -p html; cp src/gug.css html/
-
-html/images: $(PNG_FILES)
-	mkdir -p html/images; cp -fv $(PNG_FILES) html/images/
-
-#
-# PDF manual build
-#
-
-book: book/gug.pdf
+html: build/html/index.html
 
-book/gug.fo: $(XML_FILES) src/book.xslt docbook-xsl
-	cd src; xsltproc -o ../book/gug.fo --xinclude book.xslt gug.xml
-
-book/gug.pdf: book/gug.fo
-	cd src; fop -c fop-conf.xml -fo ../book/gug.fo -pdf ../book/gug.pdf
+build/html/index.html: $(PNG_FILES) $(RST_FILES)
+	sphinx-build -b html -d build/doctrees src/ build/html
 

README

@@ -18,68 +18,31 @@ snapshot copies of each release are included in the release archives:
 ------------------------------------------------------------
 
 The guacamole-manual package is the base documentation for the entire Guacamole
-stack. It is written in DocBook, an XML schema commonly used for authoring
-manuals and technical documentation.
+stack. It is written in reStructuredText, a plaintext markup syntax commonly
+used for authoring manuals and technical documentation.
 
-The build process involves running the Guacamole manual XML through an XSLT
-processor called "xsltproc", applying the standard DocBook XSL stylesheets.
+The build process involves running the Guacamole manual source through the
+tooling provided by the Sphinx project, in particular "sphinx-build".
 
 
 ------------------------------------------------------------
  Building the manual
 ------------------------------------------------------------
 
+1) Ensure Sphinx and the default ReadTheDocs theme are installed. These can be
+   installed using "pip" via the "sphinx" and "sphinx_rtd_theme" packages
+   respectively.
 
-1) Ensure the DocBook XSL stylesheets are installed
+   https://pypi.org/project/Sphinx/
+   https://pypi.org/project/sphinx-rtd-theme/
 
-   Most Linux distributions will provide a "docbook-xsl" or similarly-named
-   package which install the DocBook stylesheets in a system-wide manner. You
-   will need to either install these packages, or download the DocBook XSL
-   stylesheets yourself:
-
-   https://sourceforge.net/projects/docbook/files/docbook-xsl/
-
-2) Ensure the DOCBOOK_PATH environment variable is set
-
-    The manual build process depends on an environment variable, DOCBOOK_PATH,
-    which points to the directory in which the DocBook XSL files can be found.
-
-    This will be the directory that contains the following files:
-
-        fo/docbook.xsl
-        html/chunk.xsl
-
-    $ export DOCBOOK_PATH=/usr/share/sgml/docbook/xsl-ns-stylesheets-1.78.1
-
-3) Ensure xsltproc and fop are installed
-
-    If you do not have xsltproc, the manual will not build. The provided
-    Makefile depends entirely on using xsltproc to process the Guacamole manual
-    XML through the installed DocBook stylesheets.
-
-    Although not required for building the HTML manual, if you do not have fop
-    (Apache FOP), the PDF version of the manual cannot be built. The build
-    process uses fop to transform a ".fo" file into the PDF.
-
-4) Run make
+2) Run make
 
     $ make
 
-    The manual will now be built using xsltproc. Once complete, the entire
-    HTML version of the manual will be available within the "html" directory in
-    the root directory of the source tree, and the PDF version will be
-    available within the "book" directory as "gug.pdf".
-
-    The default build target, "all", will build both the HTML and PDF versions
-    of the manual. If you only wish to build the HTML manual, you can specify
-    the "html" target explicitly:
-
-    $ make html
-
-    Similarly, if you only wish to build the PDF, you can force this by
-    explicitly specifying the "book" target:
-
-    $ make book
+    The manual will now be built using Sphinx. Once complete, the entire
+    HTML version of the manual will be available within the "build/html"
+    directory in the root directory of the source tree.
 
 
 ------------------------------------------------------------
@@ -90,9 +53,9 @@ The guacamole-manual package includes a Dockerfile that can be used to build
 an Apache httpd Docker image that contains the Guacamole user manual.
 
 By building and running the resulting container, a developer can work on the 
-user manual without the need to install docbook and related dependencies on 
-his/her workstation. The resulting container can also be used to serve the 
-manual to Guacamole users on a network.
+user manual without the need to install Sphinx on their workstation. The
+resulting container can also be used to serve the  manual to Guacamole users on
+a network.
 
 Docker CE version 1.6 or later is required to build the image.
 
@@ -117,15 +80,6 @@ As a developer working on the documentation, it will be necessary to stop the
 container and run the build again each time you wish to see changes you've 
 made to the documentation source.
 
-By default, the container image will contain only the HTML variant of the 
-Guacamole user manual. If you also wish to serve the PDF variant, use the 
-following command to build container image
-
-    $ docker image build --build-arg TARGET=all -t guacamole/manual .
-
-You can view the PDF variant of the manual by accessing 
-http://localhost:8080/gug.pdf using your web browser.
-
 
 ------------------------------------------------------------
  Reporting problems