sort/doc/Jamfile.v2

# Spreadsort documentation Jamfile
# Copyright (c) 2014 Steven Ross
#
# Distributed under the Boost Software License,
# Version 1.0. (See accompanying file LICENSE_1_0.txt
# or copy at http://boost.org/LICENSE_1_0.txt)

# Reminder: whitespace MUST terminate variable name!
# so spaces or newlines BEFORE ; and : and AFTER too.
# (because : and ; are keywords!)

import doxygen ;
import quickbook ;
import os ; # Needed to get environment variables.
import modules ;

path-constant here : . ; # convenient to refer to files in the same directory as this jamfile.v2
path-constant boost-images : ../../../doc/src/images ;
path-constant images_location : ./doc ; # location of SVG and PNG images referenced by Quickbook.
# http://docbook.sourceforge.net/release/xsl/1.77.1/doc/html/img.src.path.html
# relative to /doc ?

path-constant parent : .. ;  # Beman Dawes - so that inspect.exe will start in boost-root/libs/timer
                             # when run from another directory, such as boost-root/status
using auto-index ;
using doxygen ;  # Required if you want to use Doxygen.
using quickbook ;
using boostbook ;

if --enable-index in  [ modules.peek : ARGV ]
{
   ECHO "Building the Spreadsort docs with automatic index generation enabled." ;
   using auto-index ;
   project sort_doc : requirements
             <auto-index>on
             <auto-index-script>sort.idx
             <auto-index-prefix>.
             <auto-index-verbose>on
             <format>html:<auto-index-internal>on
             <format>html:<xsl:param>generate.index=0
             <format>pdf:<auto-index-internal>on
             <format>pdf:<xsl:param>index.on.type=1
             <quickbook-define>enable_index ;
}
else
{
   project sort_doc ;
   ECHO "Building the Spreadsort docs with automatic index generation disabled. Try building with --enable-index." ;
}

doxygen autodoc
  :
    [ glob $(here)/../include/boost/sort.hpp ]
    [ glob $(here)/../include/boost/sort/spreadsort/*.hpp ]
    # [ glob $(here)/../include/boost/sort/detail/spreadsort/*.hpp ] # Hide implementation/detail for now.
    # but could also include this and switch Boost.Sort C++ reference info to include implementation/detail or not using Doxygen macro DETAIL.
    # See http://www.stack.nl/~dimitri/doxygen/manual/commands.html#cmdcond
    # and http://www.stack.nl/~dimitri/doxygen/manual/config.html#cfg_enabled_sections
    # by adding this line below with other Doxygen parameters
    #     <doxygen:param>ENABLED_SECTIONS="DETAIL"
    #  Or setting this macro value ENABLED_SECTIONS="DETAIL" in /doxygen/sort_doxyfile.txt for Standalone Doxygen documentaation.
    # This might be useful for maintainers.

  :
    <doxygen:param>PROJECT_NAME="Sort"
    <doxygen:param>RECURSIVE=NO
    <doxygen:param>ENABLE_PREPROCESSING=YES
    <doxygen:param>EXPAND_ONLY_PREDEF=YES
    <doxygen:param>EXTRACT_ALL=NO
    <doxygen:param>EXTRACT_PRIVATE=NO
    <doxygen:param>HIDE_UNDOC_MEMBERS=YES
    <doxygen:param>MACRO_EXPANSION=YES
    <doxygen:param>SORT_MEMBER_DOCS=NO
    <doxygen:param>SHOW_INCLUDE_FILES=NO
    <doxygen:param>MAX_INITIALIZER_LINES=0
    <doxygen:param>VERBATIM_HEADERS=NO
    <doxygen:param>WARNINGS=NO # If WARN_IF_UNDOCUMENTED is set to YES, then doxygen will generate warnings for undocumented members.
    # If EXTRACT_ALL is set to YES then this flag will automatically be disabled.
    <doxygen:param>WARN_IF_UNDOCUMENTED=NO # If WARN_IF_UNDOCUMENTED is set to YES,
    # then doxygen will generate warnings for all undocumented members.
    <doxygen:param>WARN_IF_DOC_ERROR=YES # If WARN_IF_DOC_ERROR is set to YES, Doxygen will generate warnings for
    # potential errors in the documentation.
    <doxygen:param>WARN_LOGFILE=AutoDoxywarnings.log # This may not be empty (usually not a good sign!), depending on options chosen.
    # Much better to send message to a logfile than the default stderr.
    # and make sure that there are no Doxygen errors or significant warnings in the log file.

    #<reftitle>"Reference" # Default is "Reference" but helpful to specify library.
    <xsl:param>"boost.doxygen.reftitle=Boost.Sort C++ Reference"
    # See Doxygen configuration for detailed explanation of these options.
  ;

xml sort
  :
    sort.qbk # This is your 'root' Quickbook file (that may include other .qbk files).
  ;

boostbook standalone
  :
    sort
  :
  # http://www.sagehill.net/docbookxsl/SectionNumbering.html
  <xsl:param>boost.root=../../../.. # modular-boost
  <xsl:param>chapter.autolabel=0 # No Chapter numbering.
  <xsl:param>chunk.section.depth=8
  <xsl:param>toc.section.depth=8  # How far down sections get TOCs.
  <xsl:param>toc.max.depth=4  # Max depth in each TOC.
  <xsl:param>generate.section.toc.level=1


  # PDF Options:
  # TOC Generation: this is needed for FOP-0.9 and later:
  <xsl:param>fop1.extensions=0
  <xsl:param>xep.extensions=1
  # TOC generation: this is needed for FOP 0.2, but must not be set to zero for FOP-0.9!
  <xsl:param>fop.extensions=1
  # No indent on body text:
  <xsl:param>body.start.indent=0pt
  # Margin size:
  <xsl:param>page.margin.inner=0.5in
  # Margin size:
  <xsl:param>page.margin.outer=0.5in
  # Paper type = A4
  <xsl:param>paper.type=A4
  # Yes, we want graphics for admonishments:
  <xsl:param>admon.graphics=1
  #<format>html:<xsl:param>img.src.path=$(images_location)/
  # Default works for html, need ./doc for PDF
  # Set this one for PDF generation *only*:
  # default png graphics are awful in PDF form,
  # better use SVGs instead, if available:

  <format>pdf:<xsl:param>img.src.path=$(images_location)/
  <format>pdf:<xsl:param>admon.graphics.extension=".svg"
  <format>pdf:<xsl:param>admon.graphics.path=$(boost-images)/

  <dependency>autodoc #

  ;

install pdfinstall
    : standalone
    : <location>. <install-type>PDF <name>sort.pdf
    ;
explicit css ;
explicit images ;

# This will run the inspect tool automatically from the doc folder
# but sadly seems to build the tool each time so is very slow.
#  Also it produces lots of output from the original docs.
#  So not very useful yet.

#  Run inspect tool.
# run /boost/tools/inspect//inspect/<variant>release
#  : $(parent) -text -brief # command line
#  : # input files
#  : <dependency>/boost/filesystem//boost_filesystem
#    <test-info>always_show_run_output # requirements
#  : inspect # test name
# ;

###############################################################################
alias boostdoc ;
explicit boostdoc ;
alias boostrelease : standalone ;
explicit boostrelease ;