Boost C++ Libraries

...one of the most highly regarded and expertly designed C++ library projects in the world. Herb Sutter and Andrei Alexandrescu, C++ Coding Standards

This is the documentation for a snapshot of the master branch, built from commit 1125923601.

libs/beast/doc/Jamfile

#
# Copyright (c) 2013-2017 Vinnie Falco (vinnie dot falco at gmail dot com)
#
# 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)
#

project beast/doc ;

import os ;
import path ;
import boostbook ;
import quickbook ;
import xsltproc ;
import doxygen ;
import modules ;
import saxonhe ;
import common ;

#-------------------------------------------------------------------------------
#
# Build the list of header files that Doxygen will scan. We need
# this list to inform the build system of the dependencies so the
# docs can be rebuild if any of the header files change.
#

local sources = [ path.glob-tree ../include/boost/beast : *.hpp *.ipp : detail impl ] ;

# Get the configured paths to doxygen and xsltproc

.doxygen = [ doxygen.name ] ;
.doxygen ?= doxygen ;

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

.xsltproc = [ xsltproc.name ] ;
.xsltproc ?= xsltproc ;

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

#-------------------------------------------------------------------------------
#
# Invoke Doxygen to process the header files and produce the XML
# containing the description of the C++ declarations and extracted
# Javadoc comments.
#
make index.xml
    :
        ./source.dox
    :
        @make_doxygen_xml
    :
        <dependency>$(sources)
    ;

rule make_doxygen_xml ( targets * : sources * : properties * )
{
    LIB_DIR on $(targets) =
        [ path.native [ path.parent [ path.root
        [ on $(sources[1]) return $(SEARCH) ] [ path.pwd ] ] ] ] ;
}

if [ os.name ] = NT
{
    actions make_doxygen_xml
    {
        SET LIB_DIR=$(LIB_DIR)
        SET XML_OUTPUT=$(1:D)
        "$(.doxygen)" $(2)
    }
}
else
{
    actions make_doxygen_xml
    {
        export LIB_DIR=$(LIB_DIR)
        export XML_OUTPUT=$(1:D)
        "$(.doxygen)" $(2)
    }
}

#-------------------------------------------------------------------------------
#
# 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_dir
    ;

make stage2/results
    :
        stage1/results
        stage2.xsl

        # additional dependencies
        emphasized-types.xsl
    :
        saxonhe.saxonhe_dir
    ;

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) ;
}

make reference.xml
    :
        combine.xslt
        index.xml
    :
        @call-xsltproc
    ;

actions call-xsltproc
{
    "$(.xsltproc)" $(2) > $(1)
}

#-------------------------------------------------------------------------------
#
# Produce the reference.qbk file by running
# the reference xml through the transform.
#
#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
#
install qbk : reference.qbk ;

#-------------------------------------------------------------------------------
#
# Produce the Boost.Book XML from the QuickBook
#

install images
    :
        images/message.png
    :
        <location>html/beast/images
    ;

explicit images ;

xml beast_doc
    :
        qbk/main.qbk
    :
        <dependency>images
        <dependency>qbk
    ;

explicit beast_doc ;

#-------------------------------------------------------------------------------
#
# HTML documentation for $(BOOST_ROOT)/doc/html
#
#-------------------------------------------------------------------------------

boostbook beast
    :
        beast_doc
    :
        <xsl:param>boost.root=../../../..
        <xsl:param>chapter.autolabel=1
        <xsl:param>chunk.section.depth=8                # Depth to which sections should be chunked
        <xsl:param>chunk.first.sections=1               # Chunk the first top-level section?
        <xsl:param>toc.section.depth=8                  # How deep should recursive sections appear in the TOC?
        <xsl:param>toc.max.depth=8                      # How many levels should be created for each TOC?
        <xsl:param>generate.section.toc.level=8         # Control depth of TOC generation in sections
        <xsl:param>generate.toc="chapter toc,title section nop reference nop"
        <include>../../../tools/boostbook/dtd
    :
        <dependency>images
    ;

#-------------------------------------------------------------------------------
#
# These are used to inform the build system of the
# means to build the integrated and stand-alone docs.
#

alias boostdoc ;
explicit boostdoc ;

alias boostrelease : beast ;
explicit boostrelease ;