1# 2# Copyright (c) 2013-2017 Vinnie Falco (vinnie dot falco at gmail dot com) 3# 4# Distributed under the Boost Software License, Version 1.0. (See accompanying 5# file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) 6# 7 8project beast/doc ; 9 10import os ; 11import path ; 12import boostbook ; 13import quickbook ; 14import xsltproc ; 15import doxygen ; 16import modules ; 17import saxonhe ; 18import common ; 19 20#------------------------------------------------------------------------------- 21# 22# Build the list of header files that Doxygen will scan. We need 23# this list to inform the build system of the dependencies so the 24# docs can be rebuild if any of the header files change. 25# 26 27local sources = [ path.glob-tree ../include/boost/beast : *.hpp *.ipp : detail impl ] ; 28 29# Get the configured paths to doxygen and xsltproc 30 31.doxygen = [ doxygen.name ] ; 32.doxygen ?= doxygen ; 33 34#ECHO Using doxygen from "$(.doxygen)" ; 35 36.xsltproc = [ xsltproc.name ] ; 37.xsltproc ?= xsltproc ; 38 39#ECHO Using xsltproc from "$(.xsltproc)" ; 40 41#------------------------------------------------------------------------------- 42# 43# Invoke Doxygen to process the header files and produce the XML 44# containing the description of the C++ declarations and extracted 45# Javadoc comments. 46# 47make index.xml 48 : 49 ./source.dox 50 : 51 @make_doxygen_xml 52 : 53 <dependency>$(sources) 54 ; 55 56rule make_doxygen_xml ( targets * : sources * : properties * ) 57{ 58 LIB_DIR on $(targets) = 59 [ path.native [ path.parent [ path.root 60 [ on $(sources[1]) return $(SEARCH) ] [ path.pwd ] ] ] ] ; 61} 62 63if [ os.name ] = NT 64{ 65 actions make_doxygen_xml 66 { 67 SET LIB_DIR=$(LIB_DIR) 68 SET XML_OUTPUT=$(1:D) 69 "$(.doxygen)" $(2) 70 } 71} 72else 73{ 74 actions make_doxygen_xml 75 { 76 export LIB_DIR=$(LIB_DIR) 77 export XML_OUTPUT=$(1:D) 78 "$(.doxygen)" $(2) 79 } 80} 81 82#------------------------------------------------------------------------------- 83# 84# Copy all the XSLT modules to the target directory. 85# 86# FIXME: Change this so we can just specify a directory, 87# rather than every file individually. 88# 89# Also, somehow force dependencies in a general way 90# such that the XSLT has to be executed again 91# if any of the modules change. For example, 92# if base-extract-xml-pages.xml changes, then 93# an invocation of extract-xml-pages.xsl (which 94# imports the former) must be run again. 95# 96path-constant docca : ../../../tools/docca ; 97make extract-xml-pages.xsl : $(docca)/include/docca/extract-xml-pages.xsl : @copy_script ; 98make base-extract-xml-pages.xsl : $(docca)/include/docca/base-extract-xml-pages.xsl : @copy_script ; 99make common.xsl : $(docca)/include/docca/common.xsl : @copy_script ; 100make stage1.xsl : $(docca)/include/docca/stage1.xsl : @copy_script ; 101make base-stage1.xsl : $(docca)/include/docca/base-stage1.xsl : @copy_script ; 102make stage2.xsl : $(docca)/include/docca/stage2.xsl : @copy_script ; 103make base-stage2.xsl : $(docca)/include/docca/base-stage2.xsl : @copy_script ; 104make assemble-quickbook.xsl : $(docca)/include/docca/assemble-quickbook.xsl : @copy_script ; 105make emphasized-types.xsl : $(docca)/include/docca/emphasized-types.xsl : @copy_script ; 106make base-config.xsl : $(docca)/include/docca/base-config.xsl : @copy_script ; 107 108# Copy the project-specific config XSLT 109make custom-overrides.xsl : xsl/custom-overrides.xsl : @copy_script ; 110 111# Make a copy of the given file. 112# 113actions copy_script 114{ 115 cp $(2[1]) $(1) 116} 117 118 119# This is to initially create the directory as a side effect; I'm sure there's a better way... 120make xml-pages/directory/placeholder : index.xml : @null_action ; 121 122#------------------------------------------------------------------------------- 123# 124# Run index.xml through the first transformation stage 125# (assembling and splitting the XML into page-specific files). 126# 127make xml-pages.xml 128 : 129 index.xml 130 extract-xml-pages.xsl 131 132 # Make bjam aware of additional dependencies 133 base-extract-xml-pages.xsl 134 base-config.xsl 135 custom-overrides.xsl 136 common.xsl 137 : 138 saxonhe.saxonhe 139 ; 140 141# This is just to make the directory eligible as a source 142make xml-pages : index.xml : @null_action ; 143 144# Not ready for prime time until I figure out how to get the xslt-visualizer code in place 145#make stage1/code-trace-enabled/stage1.xsl 146# : 147# stage1.xsl 148# xslt-visualizer/xsl/trace-enable.xsl 149# : 150# saxonhe.saxonhe 151# ; 152 153# This is to initially create the directory as a side effect; I'm sure there's a better way... 154make stage1/results/directory/placeholder : xml-pages.xml : @null_action ; 155make stage2/results/directory/placeholder : xml-pages.xml : @null_action ; 156 157# TODO: figure out why this (and the following stage) get built every time 158make stage1/results 159 : 160 xml-pages 161 stage1.xsl 162 163 # additional dependencies 164 xml-pages.xml 165 base-stage1.xsl 166 base-config.xsl 167 custom-overrides.xsl 168 common.xsl 169 : 170 saxonhe.saxonhe_dir 171 ; 172 173make stage2/results 174 : 175 stage1/results 176 stage2.xsl 177 178 # additional dependencies 179 emphasized-types.xsl 180 base-stage2.xsl 181 base-config.xsl 182 custom-overrides.xsl 183 common.xsl 184 : 185 saxonhe.saxonhe_dir 186 ; 187 188make reference.qbk 189 : 190 xml-pages.xml 191 assemble-quickbook.xsl 192 193 # TODO: make this input to the XSLT somehow 194 # rather than relying on it being hard-coded 195 # in the XSLT (which it is!) 196 stage2/results 197 : 198 saxonhe.saxonhe 199 ; 200 201actions make_dir 202{ 203 mkdir $(1) 204} 205 206make combine.xslt : index.xml : @null_action ; 207 208actions touch_file 209{ 210 touch $(1) ; 211} 212 213actions null_action 214{ 215 touch -c $(1) ; 216} 217 218make reference.xml 219 : 220 combine.xslt 221 index.xml 222 : 223 @call-xsltproc 224 ; 225 226actions call-xsltproc 227{ 228 "$(.xsltproc)" $(2) > $(1) 229} 230 231#------------------------------------------------------------------------------- 232# 233# Produce the reference.qbk file by running 234# the reference xml through the transform. 235# 236#make reference.qbk 237# : 238# reference.xml 239# transform.xsl 240# : 241# saxonhe.saxonhe 242# ; 243 244# We have to make a copy of reference.qbk and put it 245# in a place where the static .qbk files can find it 246# 247install qbk : reference.qbk ; 248 249#------------------------------------------------------------------------------- 250# 251# Produce the Boost.Book XML from the QuickBook 252# 253 254install images 255 : 256 images/message.png 257 : 258 <location>html/beast/images 259 ; 260 261explicit images ; 262 263xml beast_doc 264 : 265 qbk/main.qbk 266 : 267 <dependency>images 268 <dependency>qbk 269 ; 270 271explicit beast_doc ; 272 273#------------------------------------------------------------------------------- 274# 275# HTML documentation for $(BOOST_ROOT)/doc/html 276# 277#------------------------------------------------------------------------------- 278 279boostbook beast 280 : 281 beast_doc 282 : 283 <xsl:param>boost.root=../../../.. 284 <xsl:param>chapter.autolabel=1 285 <xsl:param>chunk.section.depth=8 # Depth to which sections should be chunked 286 <xsl:param>chunk.first.sections=1 # Chunk the first top-level section? 287 <xsl:param>toc.section.depth=8 # How deep should recursive sections appear in the TOC? 288 <xsl:param>toc.max.depth=8 # How many levels should be created for each TOC? 289 <xsl:param>generate.section.toc.level=8 # Control depth of TOC generation in sections 290 <xsl:param>generate.toc="chapter toc,title section nop reference nop" 291 <include>../../../tools/boostbook/dtd 292 : 293 <dependency>images 294 ; 295 296#------------------------------------------------------------------------------- 297# 298# These are used to inform the build system of the 299# means to build the integrated and stand-alone docs. 300# 301 302alias boostdoc ; 303explicit boostdoc ; 304 305alias boostrelease : beast ; 306explicit boostrelease ; 307
