Normalize doc build scripts

CHANGELOG.md

@@ -11,6 +11,7 @@ Version 86:
 * Update copyrights
 * Remove spurious declaration
 * Tidy up Jamfile
+* Normalize doc build scripts
 
 --------------------------------------------------------------------------------
 

doc/.gitignore

@@ -1,4 +1,4 @@
 html
 temp
-reference.qbk
 out.txt
+qbk/reference.qbk

doc/Jamfile

@@ -7,31 +7,133 @@
 
 project beast/doc ;
 
-import boostbook : boostbook ;
+import os ;
-
+import path ;
-using boostbook ;
+import boostbook ;
-using quickbook ;
+import quickbook ;
-using doxygen ;
 
+#-------------------------------------------------------------------------------
 #
-# HTML documentation for $(BOOST_ROOT)/doc/html
+# Build the list of header files that Doxygen will scan. We need
+# this list to inform the build system of the dependencies so the
+# docs can be rebuild if any of the header files change.
 #
 
+local sources = [ path.glob-tree ../include/boost/beast : *.hpp *.ipp : detail impl ] ;
+
+#-------------------------------------------------------------------------------
+#
+# Generate transform.xsl. This xsl transfomration takes as input
+# the Doxygen-generated XML and produces QuickBook output.
+#
+make transform.xsl
+    :
+        docca/include/docca/doxygen.xsl
+        xsl/config.xsl
+        xsl/class_detail.xsl
+        xsl/includes.xsl
+        xsl/includes_foot.xsl
+    :
+        @make_transform
+    ;
+
+# Make a copy of the docca transform. Then, insert our
+# customizations into the speciall marked locations using sed.
+#
+actions make_transform
+{
+    cp $(2[1]) $(1)
+    sed -i -e "/<!-- CONFIG_TEMPLATE -->/{r $(2[2])" -e "d}" $(1)
+    sed -i -e "/<!-- CLASS_DETAIL_TEMPLATE -->/{r $(2[3])" -e "d}" $(1)
+    sed -i -e "/<!-- INCLUDES_TEMPLATE -->/{r $(2[4])" -e "d}" $(1)
+    sed -i -e "/<!-- INCLUDES_FOOT_TEMPLATE -->/{r $(2[5])" -e "d}" $(1)
+}
+
+#-------------------------------------------------------------------------------
+#
+# Invoke Doxygen to process the header files and produce the XML
+# containing the description of the C++ declarations and extracted
+# Javadoc comments.
+#
+make reference.xml
+    :
+        ./source.dox
+    :
+        @make_xml
+    :
+        <dependency>$(sources)
+    ;
+
+# Windows is a little different from other platforms
+if [ os.name ] = NT
+{
+    actions make_xml
+    {
+        SET LIB_DIR=$(2:B=:S=..)
+        SET XML_OUTPUT=$(1:D)
+        doxygen $(2) && xsltproc $(1:B=combine:S=.xslt) $(1:B=index:S=.xml) > $(1)
+    }
+}
+else
+{
+    actions make_xml
+    {
+        export LIB_DIR=$(2:B=:S=..)
+        export XML_OUTPUT=$(1:D)
+        doxygen $(2) && xsltproc $(1:B=combine:S=.xslt) $(1:B=index:S=.xml) > $(1)
+    }
+}
+
+#-------------------------------------------------------------------------------
+#
+# Produce the reference.qbk file by running
+# the reference xml through the transform.
+#
+make reference.qbk
+    :
+        transform.xsl
+        reference.xml
+    :
+        @make_reference
+    ;
+
+actions make_reference
+{
+    xsltproc $(2) > $(1)
+}
+
+# We have to make a copy of reference.qbk and put it
+# in a place where the static .qbk files can find it
+#
+install qbk : reference.qbk ;
+
+#-------------------------------------------------------------------------------
+#
+# Produce the Boost.Book XML from the QuickBook
+#
 xml beast_doc
     :
         qbk/00_main.qbk
+    :
+        <dependency>qbk
     ;
 
 explicit beast_doc ;
 
-install beast_doc_images
+install images
     :
         images/message.png
     :
         <location>html/beast/images
     ;
 
-explicit beast_doc_images ;
+explicit images ;
+
+#-------------------------------------------------------------------------------
+#
+# HTML documentation for $(BOOST_ROOT)/doc/html
+#
+#-------------------------------------------------------------------------------
 
 boostbook beast
     :
@@ -48,10 +150,16 @@ boostbook beast
         <xsl:param>generate.toc="chapter toc,title section nop reference nop"
         <include>../../../tools/boostbook/dtd
     :
-        <dependency>beast_doc_images
+        <dependency>images
     ;
 
 
+#-------------------------------------------------------------------------------
+#
+# These are used to inform the build system of the
+# means to build the integrated and stand-alone docs.
+#
+
 alias boostdoc : beast : : : ;
 
 explicit boostdoc ;

doc/makeqbk.sh

@@ -1,16 +0,0 @@
-#!/bin/sh
-
-# Copyright (c) 2013-2017 Vinnie Falco (vinnie dot falco at gmail dot com)
-#
-# Distributed under the Boost Software License, Version 1.0. (See accompanying
-# file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
-
-mkdir -p temp
-doxygen source.dox
-cd temp
-xsltproc combine.xslt index.xml > all.xml
-cp ../docca/include/docca/doxygen.xsl doxygen.xsl
-sed -i -e '/<!-- CLASS_DETAIL_TEMPLATE -->/{r ../xsl/class_detail.xsl' -e 'd}' doxygen.xsl
-sed -i -e '/<!-- INCLUDES_TEMPLATE -->/{r ../xsl/includes.xsl' -e 'd}' doxygen.xsl
-sed -i -e '/<!-- INCLUDES_FOOT_TEMPLATE -->/{r ../xsl/includes_foot.xsl' -e 'd}' doxygen.xsl
-xsltproc ../xsl/reference.xsl all.xml > ../reference.qbk

doc/qbk/00_main.qbk

@@ -7,7 +7,7 @@
 
 [library Beast
     [quickbook 1.6]
-    [copyright 2013 - 2017 Vinnie Falco]
+    [copyright 2016 - 2017 Vinnie Falco]
     [purpose Networking Protocol Library]
     [license
         Distributed under the Boost Software License, Version 1.0.
@@ -22,15 +22,15 @@
 [template mdash[] '''— ''']
 [template indexterm1[term1] '''<indexterm><primary>'''[term1]'''</primary></indexterm>''']
 [template indexterm2[term1 term2] '''<indexterm><primary>'''[term1]'''</primary><secondary>'''[term2]'''</secondary></indexterm>''']
-[template repo_file[path] '''<ulink url="https://github.com/boostorg/Beast/blob/master/'''[path]'''">'''[path]'''</ulink>''']
+[template repo_file[path] '''<ulink url="https://github.com/boostorg/beast/blob/master/'''[path]'''">'''[path]'''</ulink>''']
-[template include_file[path][^<'''<ulink url="https://github.com/boostorg/Beast/blob/master/include/'''[path]'''">'''[path]'''</ulink>'''>]]
+[template include_file[path][^<'''<ulink url="https://github.com/boostorg/beast/blob/master/include/'''[path]'''">'''[path]'''</ulink>'''>]]
 
-[def __N3747__ [@http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2013/n3747.pdf [*N3747]]]
+[def __N3747__                  [@http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2013/n3747.pdf [*N3747]]]
-[def __N4588__ [@http://cplusplus.github.io/networking-ts/draft.pdf [*N4588]]]
+[def __N4588__                  [@http://cplusplus.github.io/networking-ts/draft.pdf [*N4588]]]
-[def __rfc6455__ [@https://tools.ietf.org/html/rfc6455 rfc6455]]
+[def __rfc6455__                [@https://tools.ietf.org/html/rfc6455 rfc6455]]
-[def __rfc7230__ [@https://tools.ietf.org/html/rfc7230 rfc7230]]
+[def __rfc7230__                [@https://tools.ietf.org/html/rfc7230 rfc7230]]
 
-[def __Asio__ [@http://www.boost.org/doc/html/boost_asio.html Boost.Asio]]
+[def __Asio__                   [@http://www.boost.org/doc/html/boost_asio.html Boost.Asio]]
 
 [def __asio_handler_invoke__    [@http://www.boost.org/doc/html/boost_asio/reference/asio_handler_invoke.html `asio_handler_invoke`]]
 [def __asio_handler_allocate__  [@http://www.boost.org/doc/html/boost_asio/reference/asio_handler_allocate.html `asio_handler_allocate`]]
@@ -106,7 +106,7 @@
 
 [block'''<reference id="beast_hidden"><title>This Page Intentionally Left Blank 1/2</title>''']
 [section:ref This Page Intentionally Left Blank 2/2]
-[include ../reference.qbk]
+[include reference.qbk]
 [endsect]
 [block'''</reference>''']
 

doc/qbk/01_intro.qbk

@@ -56,10 +56,10 @@ Beast requires:
 
 Supported compilers: msvc-14+, gcc 4.8+, clang 3.6+
 
-Sources are [*header-only]. To link a program using Beast successfully, add the
+Sources are [*header-only].
+To link a program using Beast successfully, add the
 [@http://www.boost.org/libs/system/doc/reference.html Boost.System]
-library to the list of linked libraries. If you use coroutines
+library to your build scripts. If you use coroutines you'll also need the
-you'll also need the
 [@http://www.boost.org/libs/coroutine/doc/html/index.html Boost.Coroutine]
 library. Please visit the
 [@http://www.boost.org/doc/ Boost documentation]

doc/source.dox

@@ -4,8 +4,8 @@
 DOXYFILE_ENCODING      = UTF-8
 PROJECT_NAME           = "Beast"
 PROJECT_NUMBER         =
-PROJECT_BRIEF          = C++ Library
+PROJECT_BRIEF          = C++ Networking Library
-PROJECT_LOGO           = images/beast.png
+PROJECT_LOGO           =
 OUTPUT_DIRECTORY       =
 CREATE_SUBDIRS         = NO
 ALLOW_UNICODE_NAMES    = NO
@@ -103,11 +103,11 @@ WARN_LOGFILE           =
 # Configuration options related to the input files
 #---------------------------------------------------------------------------
 INPUT = \
-        ../include/boost/beast/ \
+        $(LIB_DIR)/include/boost/beast/ \
-        ../include/boost/beast/core \
+        $(LIB_DIR)/include/boost/beast/core \
-        ../include/boost/beast/http \
+        $(LIB_DIR)/include/boost/beast/http \
-        ../include/boost/beast/websocket \
+        $(LIB_DIR)/include/boost/beast/websocket \
-        ../include/boost/beast/zlib
+        $(LIB_DIR)/include/boost/beast/zlib
 
 INPUT_ENCODING         = UTF-8
 FILE_PATTERNS          =
@@ -253,7 +253,7 @@ MAN_LINKS              = NO
 # Configuration options related to the XML output
 #---------------------------------------------------------------------------
 GENERATE_XML           = YES
-XML_OUTPUT             = temp/
+XML_OUTPUT             = $(XML_OUTPUT)
 XML_PROGRAMLISTING     = YES
 
 #---------------------------------------------------------------------------

doc/xsl/config.xsl

@@ -0,0 +1,6 @@
+<!-- Variables (Edit for your project) -->
+<xsl:variable name="doc-ref" select="'beast.ref.'"/>
+<xsl:variable name="doc-ns" select="'boost::beast'"/>
+<xsl:variable name="debug" select="0"/>
+<xsl:variable name="private" select="0"/>
+<!-- End Variables -->

doc/xsl/reference.xsl

@@ -1,13 +0,0 @@
-<?xml version="1.0" encoding="utf-8"?>
-<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version="1.0">
-
-  <!-- Variables (Edit for your project) -->
-  <xsl:variable name="doc-ref" select="'beast.ref.'"/>
-  <xsl:variable name="doc-ns" select="'boost::beast'"/>
-  <xsl:variable name="debug" select="0"/>
-  <xsl:variable name="private" select="0"/>
-  <!-- End Variables -->
-
-  <xsl:include href="../temp/doxygen.xsl"/>
-
-</xsl:stylesheet>