Fix: Adds histogram to boostbook (#273)

.gitignore

@@ -2,6 +2,7 @@ build*
 *.gcov
 doc/html
 doc/reference.xml
+doc/reference_pp.xml
 __pycache__
 *.pyc
 .DS_Store

doc/Jamfile

@@ -3,11 +3,16 @@
 # 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)
 
+# How to set up Boost Build for building the documentation:
+# https://www.boost.org/doc/libs/1_72_0/doc/html/quickbook/install.html
+
 project doc/histogram ;
 
+import os ;
 import doxygen ;
 import quickbook ;
 import boostbook : boostbook ;
+import notfile ;
 
 path-constant THIS_PATH : . ;
 
@@ -33,26 +38,40 @@ doxygen reference
                              \"BOOST_ATTRIBUTE_NODISCARD\""
 ;
 
-make reference_pp.xml : reference.xml : @doxygen_postprocessing ;
+actions doxygen-postprocessing
-actions doxygen_postprocessing
 {
-  python $(THIS_PATH)/doxygen_postprocessing.py $(>) $(<)
+  python $(THIS_PATH)/doxygen_postprocessing.py "$(>)"
 }
 
-boostbook histogram
+notfile reference-pp : @doxygen-postprocessing : reference.xml ;
+
+xml histogram
 :
-  histogram.qbk
+    histogram.qbk
 :
-  <xsl:param>boost.root=../../../..
+    <dependency>reference-pp
-  <xsl:param>boost.libraries=../../../libraries.htm
-  <xsl:param>boost.mathjax=1
-  <xsl:param>chunk.first.sections=1
-  <xsl:param>generate.toc="chapter nop section toc"
-  <xsl:param>toc.section.depth=3
-  <dependency>reference_pp.xml
 ;
 
-alias boostdoc ;
+path-constant images_location : html ;
+
+boostbook standalone
+:
+    histogram
+:
+    <xsl:param>boost.root=../../../..
+    <xsl:param>boost.libraries=../../../libraries.htm
+    <xsl:param>boost.mathjax=1
+    <xsl:param>chunk.first.sections=1
+    <xsl:param>generate.toc="chapter nop section toc"
+    <xsl:param>toc.section.depth=3
+    <format>pdf:<xsl:param>img.src.path=$(images_location)/
+    <format>pdf:<xsl:param>boost.url.prefix="http://www.boost.org/doc/libs/release/doc/html"
+;
+
+alias boostdoc
+:
+    histogram
+;
 explicit boostdoc ;
-alias boostrelease : histogram ;
+alias boostrelease ;
 explicit boostrelease ;

doc/doxygen_postprocessing.py

@@ -46,10 +46,13 @@ def is_deprecated(x):
     return False
 
 
-tree = ET.parse(sys.argv[1])
+input_file = sys.argv[1]
+output_file = input_file.replace(".xml", "_pp.xml")
+
+tree = ET.parse(input_file)
 root = tree.getroot()
 
-parent_map = {c:p for p in tree.iter() for c in p}
+parent_map = {c: p for p in tree.iter() for c in p}
 
 unspecified = ET.Element("emphasis")
 unspecified.text = "unspecified"
@@ -75,23 +78,38 @@ for item in select(is_detail, "type"):
 # hide everything that's deprecated
 for item in select(is_deprecated, "typedef"):
     parent = parent_map[item]
-    log("removing deprecated", item.tag, item.get("name"), "from", parent.tag, parent.get("name"))
+    log(
+        "removing deprecated",
+        item.tag,
+        item.get("name"),
+        "from",
+        parent.tag,
+        parent.get("name"),
+    )
     parent.remove(item)
 
 # hide private member functions
-for item in select(lambda x: x.get("name") == "private member functions", "method-group"):
+for item in select(
+    lambda x: x.get("name") == "private member functions", "method-group"
+):
     parent = parent_map[item]
     log("removing private member functions from", parent.tag, parent.get("name"))
     parent.remove(item)
 
 # hide undocumented classes, structs, functions and replace those declared
 # "implementation detail" with typedef to implementation_defined
-for item in select(lambda x:True, "class", "struct", "function"):
+for item in select(lambda x: True, "class", "struct", "function"):
     purpose = item.find("purpose")
     if purpose is None:
         parent = parent_map[item]
-        log("removing undocumented", item.tag, item.get("name"), "from",
+        log(
-            parent.tag, parent.get("name"))
+            "removing undocumented",
+            item.tag,
+            item.get("name"),
+            "from",
+            parent.tag,
+            parent.get("name"),
+        )
         if item in parent_map[item]:
             parent_map[item].remove(item)
     elif purpose.text.strip().lower() == "implementation detail":
@@ -104,13 +122,16 @@ for item in select(lambda x:True, "class", "struct", "function"):
         type.append(unspecified)
         item.append(type)
 
-parent_map = {c:p for p in tree.iter() for c in p}
+parent_map = {c: p for p in tree.iter() for c in p}
 
 # hide methods and constructors explicitly declared as "implementation detail"
 for item in select(is_detail, "constructor", "method"):
     name = item.get("name")
-    log("removing", (item.tag + " " + name) if name is not None else item.tag,
+    log(
-        "declared as implementation detail")
+        "removing",
+        (item.tag + " " + name) if name is not None else item.tag,
+        "declared as implementation detail",
+    )
     parent_map[item].remove(item)
 
-tree.write(sys.argv[2])
+tree.write(output_file)