Use superproject docca

2025-08-03 06:44:39 +02:00 · 2019-12-23 11:19:35 -08:00
parent 45cb52f651
commit af8e4278ba
7 changed files with 153 additions and 69 deletions
--- a/.gitmodules
+++ b/.gitmodules
@@ -1,4 +0,0 @@
-[submodule "docca"]
-	path = doc/docca
-	url = https://github.com/vinniefalco/docca.git
-    branch = .
--- a/.travis.yml
+++ b/.travis.yml
@@ -54,10 +54,11 @@ matrix:
        - BOOST_BRANCH=develop && [ "$TRAVIS_BRANCH" == "master" ] && BOOST_BRANCH=master || true
        - git clone -b $BOOST_BRANCH https://github.com/boostorg/boost.git boost-root
        - cd boost-root
-        - git submodule update --init tools/boostdep
-        - git submodule update --init tools/quickbook
-        - git submodule update --init tools/boostbook
        - git submodule update --init libs/context
+        - git submodule update --init tools/boostbook
+        - git submodule update --init tools/boostdep
+        - git submodule update --init tools/docca
+        - git submodule update --init tools/quickbook
        - cp -r $TRAVIS_BUILD_DIR/* libs/beast
        - python tools/boostdep/depinst/depinst.py ../tools/quickbook
        - ./bootstrap.sh
--- a/doc/Jamfile
+++ b/doc/Jamfile
@@ -37,34 +37,6 @@ local sources = [ path.glob-tree ../include/boost/beast : *.hpp *.ipp : detail i

 #ECHO Using xsltproc from "$(.xsltproc)" ;

-#-------------------------------------------------------------------------------
-#
-# 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
@@ -106,8 +78,140 @@ else
    }
 }

+#-------------------------------------------------------------------------------
+#
+# Copy all the XSLT modules to the target directory.
+#
+# FIXME: Change this so we can just specify a directory,
+#        rather than every file individually.
+#
+#        Also, somehow force dependencies in a general way
+#        such that the XSLT has to be executed again
+#        if any of the modules change. For example,
+#        if base-extract-xml-pages.xml changes, then
+#        an invocation of extract-xml-pages.xsl (which
+#        imports the former) must be run again.
+#
+path-constant docca : ../../../tools/docca ;
+make extract-xml-pages.xsl      : $(docca)/include/docca/extract-xml-pages.xsl      : @copy_script ;
+make base-extract-xml-pages.xsl : $(docca)/include/docca/base-extract-xml-pages.xsl : @copy_script ;
+make common.xsl                 : $(docca)/include/docca/common.xsl                 : @copy_script ;
+make stage1.xsl                 : $(docca)/include/docca/stage1.xsl                 : @copy_script ;
+make base-stage1.xsl            : $(docca)/include/docca/base-stage1.xsl            : @copy_script ;
+make stage2.xsl                 : $(docca)/include/docca/stage2.xsl                 : @copy_script ;
+make assemble-quickbook.xsl     : $(docca)/include/docca/assemble-quickbook.xsl     : @copy_script ;
+make emphasized-types.xsl       : $(docca)/include/docca/emphasized-types.xsl       : @copy_script ;
+
+make config.xsl
+    :
+        $(docca)/include/docca/config.xsl
+        xsl/config.xsl
+        xsl/class_detail.xsl
+        xsl/includes.xsl
+    :
+        @make_config
+    ;
+
+actions make_config
+{
+    cp $(2[1]) $(1)
+    sed -i -e "/<!-- CONFIG_TEMPLATE -->/{r $(2[2])" -e "d}" $(1)
+    sed -i -e "/<!-- INCLUDES_FOOT_TEMPLATE -->/{r $(2[4])" -e "d}" $(1)
+}
+
+# Make a copy of the given file.
+#
+actions copy_script
+{
+    cp $(2[1]) $(1)
+}
+
+
+# This is to initially create the directory as a side effect; I'm sure there's a better way...
+make xml-pages/directory/placeholder : index.xml : @null_action ;
+
+#-------------------------------------------------------------------------------
+#
+# Run index.xml through the first transformation stage
+# (assembling and splitting the XML into page-specific files).
+#
+make xml-pages.xml
+    :
+        index.xml
+        extract-xml-pages.xsl
+
+        # Make bjam aware of additional dependencies
+        base-extract-xml-pages.xsl
+        config.xsl
+        common.xsl
+    :
+        saxonhe.saxonhe
+    ;
+
+# This is just to make the directory eligible as a source
+make xml-pages : index.xml : @null_action ;
+
+# Not ready for prime time until I figure out how to get the xslt-visualizer code in place
+#make stage1/code-trace-enabled/stage1.xsl
+#    :
+#        stage1.xsl
+#        xslt-visualizer/xsl/trace-enable.xsl
+#    :
+#        saxonhe.saxonhe
+#    ;
+
+# This is to initially create the directory as a side effect; I'm sure there's a better way...
+make stage1/results/directory/placeholder : xml-pages.xml : @null_action ;
+make stage2/results/directory/placeholder : xml-pages.xml : @null_action ;
+
+# TODO: figure out why this (and the following stage) get built every time
+make stage1/results
+    :
+        xml-pages
+        stage1.xsl
+
+        # additional dependencies
+        xml-pages.xml
+        base-stage1.xsl
+        config.xsl
+        common.xsl
+    :
+        saxonhe.saxonhe
+    ;
+
+make stage2/results
+    :
+        stage1/results
+        stage2.xsl
+    :
+        saxonhe.saxonhe
+    ;
+
+make reference.qbk
+    :
+        xml-pages.xml
+        assemble-quickbook.xsl
+
+        # TODO: make this input to the XSLT somehow
+        #       rather than relying on it being hard-coded
+        #       in the XSLT (which it is!)
+        stage2/results
+    :
+        saxonhe.saxonhe
+    ;
+
+actions make_dir
+{
+    mkdir $(1)
+}
+
 make combine.xslt : index.xml : @null_action ;

+actions touch_file
+{
+    touch $(1) ;
+}
+
 actions null_action
 {
    touch -c $(1) ;
@@ -131,13 +235,13 @@ actions call-xsltproc
 # Produce the reference.qbk file by running
 # the reference xml through the transform.
 #
-make reference.qbk
-    :
-        reference.xml
-        transform.xsl
-    :
-        saxonhe.saxonhe
-    ;
+#make reference.qbk
+#    :
+#        reference.xml
+#        transform.xsl
+#    :
+#        saxonhe.saxonhe
+#    ;

 # We have to make a copy of reference.qbk and put it
 # in a place where the static .qbk files can find it
@@ -201,4 +305,4 @@ alias boostdoc ;
 explicit boostdoc ;

 alias boostrelease : beast ;
-explicit boostrelease ;
+explicit boostrelease ;
--- a/doc/docca
+++ b/doc/docca
--- a/doc/xsl/config.xsl
+++ b/doc/xsl/config.xsl
@@ -1,6 +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="doc-ref" select="'beast.ref'"/>
 <xsl:variable name="debug" select="0"/>
 <xsl:variable name="private" select="0"/>
 <!-- End Variables -->
--- a/doc/xsl/includes.xsl
+++ b/doc/xsl/includes.xsl
@@ -1,5 +1,8 @@
-<!-- INCLUDES_TEMPLATE BEGIN -->
-  <xsl:text>Defined in header [include_file </xsl:text>
-  <xsl:value-of select="substring-after($file,'include/')"/>
-  <xsl:text>]&#xd;&#xd;</xsl:text>
-<!-- INCLUDES_TEMPLATE END -->
+<!-- INCLUDES_FOOT_TEMPLATE BEGIN -->
+<xsl:template mode="convenience-header" match="@file[contains(., 'boost/beast/core')]"     >core.hpp</xsl:template>
+<xsl:template mode="convenience-header" match="@file[contains(., 'boost/beast/http')]"     >http.hpp</xsl:template>
+<xsl:template mode="convenience-header" match="@file[contains(., 'boost/beast/ssl')]"      >ssl.hpp</xsl:template>
+<xsl:template mode="convenience-header" match="@file[contains(., 'boost/beast/websocket')]">websocket.hpp</xsl:template>
+<xsl:template mode="convenience-header" match="@file[contains(., 'boost/beast/zlib')]"     >zlib.hpp</xsl:template>
+<xsl:template mode="convenience-header" match="@file"/>
+<!-- INCLUDES_FOOT_TEMPLATE END -->
--- a/doc/xsl/includes_foot.xsl
+++ b/doc/xsl/includes_foot.xsl
@@ -1,19 +0,0 @@
-<!-- INCLUDES_FOOT_TEMPLATE BEGIN -->
-  <xsl:choose>
-    <xsl:when test="contains($file, 'boost/beast/core')">
-      <xsl:text>&#xd;&#xd;Convenience header [include_file boost/beast/core.hpp]&#xd;</xsl:text>
-    </xsl:when>
-    <xsl:when test="contains($file, 'boost/beast/http')">
-      <xsl:text>&#xd;&#xd;Convenience header [include_file boost/beast/http.hpp]&#xd;</xsl:text>
-    </xsl:when>
-    <xsl:when test="contains($file, 'boost/beast/ssl')">
-      <xsl:text>&#xd;&#xd;Convenience header [include_file boost/beast/ssl.hpp]&#xd;</xsl:text>
-    </xsl:when>
-    <xsl:when test="contains($file, 'boost/beast/websocket')">
-      <xsl:text>&#xd;&#xd;Convenience header [include_file boost/beast/websocket.hpp]&#xd;</xsl:text>
-    </xsl:when>
-    <xsl:when test="contains($file, 'boost/beast/zlib')">
-      <xsl:text>&#xd;&#xd;Convenience header [include_file boost/beast/zlib.hpp]&#xd;</xsl:text>
-    </xsl:when>
-  </xsl:choose>
-<!-- INCLUDES_FOOT_TEMPLATE END -->