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 assemble-quickbook.xsl : $(docca)/include/docca/assemble-quickbook.xsl : @copy_script ; 104make emphasized-types.xsl : $(docca)/include/docca/emphasized-types.xsl : @copy_script ; 105 106make config.xsl 107 : 108 $(docca)/include/docca/config.xsl 109 xsl/config.xsl 110 xsl/class_detail.xsl 111 xsl/includes.xsl 112 : 113 @make_config 114 ; 115 116actions make_config 117{ 118 cp $(2[1]) $(1) 119 sed -i -e "/<!-- CONFIG_TEMPLATE -->/{r $(2[2])" -e "d}" $(1) 120 sed -i -e "/<!-- INCLUDES_FOOT_TEMPLATE -->/{r $(2[4])" -e "d}" $(1) 121} 122 123# Make a copy of the given file. 124# 125actions copy_script 126{ 127 cp $(2[1]) $(1) 128} 129 130 131# This is to initially create the directory as a side effect; I'm sure there's a better way... 132make xml-pages/directory/placeholder : index.xml : @null_action ; 133 134#------------------------------------------------------------------------------- 135# 136# Run index.xml through the first transformation stage 137# (assembling and splitting the XML into page-specific files). 138# 139make xml-pages.xml 140 : 141 index.xml 142 extract-xml-pages.xsl 143 144 # Make bjam aware of additional dependencies 145 base-extract-xml-pages.xsl 146 config.xsl 147 common.xsl 148 : 149 saxonhe.saxonhe 150 ; 151 152# This is just to make the directory eligible as a source 153make xml-pages : index.xml : @null_action ; 154 155# Not ready for prime time until I figure out how to get the xslt-visualizer code in place 156#make stage1/code-trace-enabled/stage1.xsl 157# : 158# stage1.xsl 159# xslt-visualizer/xsl/trace-enable.xsl 160# : 161# saxonhe.saxonhe 162# ; 163 164# This is to initially create the directory as a side effect; I'm sure there's a better way... 165make stage1/results/directory/placeholder : xml-pages.xml : @null_action ; 166make stage2/results/directory/placeholder : xml-pages.xml : @null_action ; 167 168# TODO: figure out why this (and the following stage) get built every time 169make stage1/results 170 : 171 xml-pages 172 stage1.xsl 173 174 # additional dependencies 175 xml-pages.xml 176 base-stage1.xsl 177 config.xsl 178 common.xsl 179 : 180 saxonhe.saxonhe_dir 181 ; 182 183make stage2/results 184 : 185 stage1/results 186 stage2.xsl 187 188 # additional dependencies 189 emphasized-types.xsl 190 : 191 saxonhe.saxonhe_dir 192 ; 193 194make reference.qbk 195 : 196 xml-pages.xml 197 assemble-quickbook.xsl 198 199 # TODO: make this input to the XSLT somehow 200 # rather than relying on it being hard-coded 201 # in the XSLT (which it is!) 202 stage2/results 203 : 204 saxonhe.saxonhe 205 ; 206 207actions make_dir 208{ 209 mkdir $(1) 210} 211 212make combine.xslt : index.xml : @null_action ; 213 214actions touch_file 215{ 216 touch $(1) ; 217} 218 219actions null_action 220{ 221 touch -c $(1) ; 222} 223 224make reference.xml 225 : 226 combine.xslt 227 index.xml 228 : 229 @call-xsltproc 230 ; 231 232actions call-xsltproc 233{ 234 "$(.xsltproc)" $(2) > $(1) 235} 236 237#------------------------------------------------------------------------------- 238# 239# Produce the reference.qbk file by running 240# the reference xml through the transform. 241# 242#make reference.qbk 243# : 244# reference.xml 245# transform.xsl 246# : 247# saxonhe.saxonhe 248# ; 249 250# We have to make a copy of reference.qbk and put it 251# in a place where the static .qbk files can find it 252# 253install qbk : reference.qbk ; 254 255#------------------------------------------------------------------------------- 256# 257# Produce the Boost.Book XML from the QuickBook 258# 259 260install images 261 : 262 images/message.png 263 : 264 <location>html/beast/images 265 ; 266 267explicit images ; 268 269xml beast_doc 270 : 271 qbk/main.qbk 272 : 273 <dependency>images 274 <dependency>qbk 275 ; 276 277explicit beast_doc ; 278 279#------------------------------------------------------------------------------- 280# 281# HTML documentation for $(BOOST_ROOT)/doc/html 282# 283#------------------------------------------------------------------------------- 284 285boostbook beast 286 : 287 beast_doc 288 : 289 <xsl:param>boost.root=../../../.. 290 <xsl:param>chapter.autolabel=1 291 <xsl:param>chunk.section.depth=8 # Depth to which sections should be chunked 292 <xsl:param>chunk.first.sections=1 # Chunk the first top-level section? 293 <xsl:param>toc.section.depth=8 # How deep should recursive sections appear in the TOC? 294 <xsl:param>toc.max.depth=8 # How many levels should be created for each TOC? 295 <xsl:param>generate.section.toc.level=8 # Control depth of TOC generation in sections 296 <xsl:param>generate.toc="chapter toc,title section nop reference nop" 297 <include>../../../tools/boostbook/dtd 298 : 299 <dependency>images 300 ; 301 302#------------------------------------------------------------------------------- 303# 304# These are used to inform the build system of the 305# means to build the integrated and stand-alone docs. 306# 307 308alias boostdoc ; 309explicit boostdoc ; 310 311alias boostrelease : beast ; 312explicit boostrelease ;
