diff --git a/.gitignore b/.gitignore index c4906f7e..c188a812 100644 --- a/.gitignore +++ b/.gitignore @@ -2,6 +2,7 @@ build* *.gcov doc/html doc/reference.xml +doc/reference_pp.xml __pycache__ *.pyc .DS_Store diff --git a/doc/Jamfile b/doc/Jamfile index 61278276..5f8e3818 100644 --- a/doc/Jamfile +++ b/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 : - boost.root=../../../.. - boost.libraries=../../../libraries.htm - boost.mathjax=1 - chunk.first.sections=1 - generate.toc="chapter nop section toc" - toc.section.depth=3 - reference_pp.xml + reference-pp ; -alias boostdoc ; +path-constant images_location : html ; + +boostbook standalone +: + histogram +: + boost.root=../../../.. + boost.libraries=../../../libraries.htm + boost.mathjax=1 + chunk.first.sections=1 + generate.toc="chapter nop section toc" + toc.section.depth=3 + pdf:img.src.path=$(images_location)/ + pdf:boost.url.prefix="http://www.boost.org/doc/libs/release/doc/html" +; + +alias boostdoc +: + histogram +; explicit boostdoc ; -alias boostrelease : histogram ; +alias boostrelease ; explicit boostrelease ; diff --git a/doc/doxygen_postprocessing.py b/doc/doxygen_postprocessing.py index 3584346b..cd53461f 100644 --- a/doc/doxygen_postprocessing.py +++ b/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", - parent.tag, parent.get("name")) + log( + "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, - "declared as implementation detail") + log( + "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)