ceph/src/boost/libs/circular_buffer/doc/jamfile.v2

   1
   2 #  Boost.circular_buffer library documentation Jamfile.v2
   3 #
   4 #  Copyright Paul A. Bristow 2013.
   5 #  Copyright Jan Gaspar 2003-2008.
   6
   7 #  Use, modification and distribution is subject to
   8 #  the Boost Software License, Version 1.0.
   9 #  (See accompanying file LICENSE_1_0.txt
  10 #  or copy at http://www.boost.org/LICENSE_1_0.txt)
  11
  12 path-constant nav_images :  html/images/ ; # png and svg images for home, next, note, tip...
  13 path-constant images_location : html/images ; # location of my SVG and PNG images referenced by Quickbook.
  14 path-constant pdf_images_location : .. ; # location of SVG and PNG images referenced by pdf.
  15 path-constant here : . ; # location of /doc folder.
  16
  17 # echo "nav_images = " $(nav_images) ; # "nav_images = I:\boost-trunk\libs\circular_buffer\doc\html\images
  18 # echo "images_location = " $(images_location) ; # images_location = I:\boost-trunk\libs\circular_buffer\doc\html\images
  19 # echo "pdf_images_location = " $(pdf_images_location) #
  20 import modules ;
  21 using auto-index ;
  22 using doxygen ;  # Required if you want to use Doxygen.
  23 using quickbook ;
  24
  25
  26 doxygen autodoc
  27    :
  28    #  List all the files individually (RECURSIVE=NO ).
  29       [ glob ../../../boost/circular_buffer.hpp ]
  30       [ glob ../../../boost/circular_buffer/base.hpp ]
  31       [ glob ../../../boost/circular_buffer/space_optimized.hpp ]
  32       [ glob ../../../boost/circular_buffer/details.hpp ] # Needed for capacity_control at least.
  33       [ glob ../../../boost/circular_buffer/debug.hpp ] # not needed?
  34
  35    :
  36    # Pass some setting parameters to Doxygen.
  37       <doxygen:param>WARNINGS=YES # Default NO, but useful to see warnings, especially in a logfile.
  38       # It is also wise to to set a warnings logfile like this:
  39       <doxygen:param>WARN_LOGFILE=AutoDoxywarnings.log # This may not be empty (usually not a good sign!), depending on options chosen.
  40       # Much better to send message to a logfile than the default stderr.
  41       # and make sure that there are no Doxygen errors or significant warnings in the log file.
  42       <doxygen:param>RECURSIVE=NO # Search recursively down .hpp and .cpp subdirectories.
  43       <doxygen:param>EXTRACT_ALL=NO
  44       <doxygen:param>EXTRACT_PRIVATE=NO # NO means do not extract info about private member functions and data.
  45       <doxygen:param>HIDE_UNDOC_MEMBERS=YES # Only show members that have some documentation like \param, \return ...
  46       <doxygen:param>MACRO_EXPANSION=YES # YES will expand all macro names in the source code (default = NO).
  47       <doxygen:param>EXPAND_ONLY_PREDEF=YES # If the EXPAND_ONLY_PREDEF and MACRO_EXPANSION tags are both set to YES
  48       # then the macro expansion is limited to the macros specified with the PREDEFINED and EXPAND_AS_DEFINED tags.
  49       # If EXPAND_ONLY_PREDEF tag can be used to specify a list of macro names that should be expanded (as defined).
  50       # The PREDEFINED tag can be used to specify one or more macro names that are defined
  51       # before the preprocessor is started (similar to the -D option of gcc).
  52       # The argument of the tag is a list of macros of the form:
  53       #    name or name=definition (no spaces).
  54       # If the definition and the "=" are omitted, "=1" is assumed.
  55       # To prevent a macro definition from being undefined via #undef or
  56       # recursively expanded use the := operator instead of the = operator.
  57       # See http://www.stack.nl/~dimitri/doxygen/config.html#cfg_predefined.
  58       # static char *malloc BOOST_PREVENT_MACRO_SUBSTITUTION(const size_type bytes);
  59       # will not produce a helpful Doxygen output, so
  60       # replace some with more helpful text, or none, for example:
  61       <doxygen:param>"PREDEFINED= \\
  62          \"BOOST_PREVENT_MACRO_SUBSTITUTION\" \\
  63          \"BOOST_STATIC_CONSTANT(T,V)=static x const y\" \\
  64          \"BOOST_UNITS_AUTO_STATIC_CONSTANT(a,b)=static const auto a = b\" \\
  65          \"BOOST_DEDUCED_TYPENAME=typename\" \\
  66          \"BOOST_CONSTEXPR=constexpr\" \\
  67                  \"BOOST_CONTAINER_NOEXCEPT=noexcept\" \\
  68                  \"BOOST_CONTAINER_NOEXCEPT_IF(T)=noexcept(T)\" \\
  69          \"BOOST_UNITS_TYPEOF(a)=typeof(a)\" \\
  70          \"BOOST_UNITS_HAS_TYPEOF=1\" \\
  71          \"BOOST_MPL_ASSERT(expr)=\" \\
  72          \"BOOST_ASSERT(expr)=\" \\
  73                  \"BOOST_RV_REF(T)=T &&\" \\
  74          \"ASSERT(x)=assert(x)\" \\
  75          \"__cplusplus \""
  76       # BOOST_PREVENT_MACRO_SUBSTITUTION,  will not be replaced by ,
  77       # BOOST_STATIC_CONSTANT will be replaced by "static x const y",
  78       # BOOST_DEDUCED_TYPENAME will be replaced by "typename",
  79       # BOOST_CONSTEXPR will be replaced by "constexpr".
  80       <doxygen:param>EXCLUDE_SYMBOLS=*_throws
  81       # <doxygen:param>IMAGE_PATH="../images" # for circular_buffer.png
  82       #  See autodoxywarnings.log to check this is correct.
  83
  84       # The syntax hoops to jump through are 'interesting' for more than one PREDEFINED,
  85       # and to permit spaces within definitions (use double quotes).
  86       # Don't forget that every double quote " needs a preceeding \trip character!
  87       # and that each trailing continuation \ needs a preceeding \trip character too!
  88       # And finally that if more than one item is included (as here) the whole is
  89       # enclosed in "PREDEFINED=... ", but without a leading \.  Go figure...
  90
  91       # A grep for PREDEFINED= in jamfiles will reveal even more complex examples.
  92       # Boost Libraries with useful examples are: Accumulators, Interprocess, MPI, Random, Units, Expressive.
  93
  94       # Optionally, you can provide a Reference section name specific for your library, for example:
  95       <xsl:param>"boost.doxygen.reftitle=Boost.Circular_buffer C++ Reference"
  96    ;
  97
  98 xml circular_buffer : circular_buffer.qbk ;
  99
 100 using boostbook ;
 101
 102 boostbook standalone
 103    :
 104       circular_buffer
 105    :
 106
 107    # General settings
 108    # =================
 109    <format>html:<xsl:param>boost.root=../../../..
 110    <format>html:<xsl:param>img.src.path=../../../../doc/html/
 111    <format>docbook:<xsl:param>boost.root=boost:
 112
 113     # Options for html and pdf
 114     # ========================
 115     # No indent on body text:
 116     <xsl:param>body.start.indent=0pt
 117     # Margin size:
 118     <xsl:param>page.margin.inner=0.5in
 119     # Margin size:
 120     <xsl:param>page.margin.outer=0.5in
 121     # Yes, we want graphics for admonishments:
 122     <xsl:param>admon.graphics=1
 123
 124     # HTML options:
 125     # =============
 126     # Use graphics icons not text for navigation:
 127     <xsl:param>navig.graphics=1
 128     # How far down we chunk nested sections, basically all of them:
 129     <xsl:param>chunk.section.depth=2
 130     # Don't put the first section on the same page as the TOC itself:
 131     <xsl:param>chunk.first.sections=1
 132     # How far down sections get TOC's
 133     <xsl:param>toc.section.depth=4
 134     # Max depth in each TOC:
 135     <xsl:param>toc.max.depth=2
 136     # How far down we go with TOC's
 137     <xsl:param>generate.section.toc.level=10
 138     # Horizontal ? spacing in table cells.
 139     <format>html:<xsl:param>html.cellspacing=3 # pixels
 140     # Vertical spacing in table cells.
 141     <format>html:<xsl:param>html.cellpadding=5 # pixels
 142     #  Not sure if these are right way round?
 143
 144         <auto-index>on # Turns on index (or off).
 145         # Turns on (or off) index-verbose for diagnostic info (using /bin auto-index-verbose folders).
 146         <auto-index-verbose>on
 147
 148         <format>pdf:<auto-index-internal>off # on (or off) to use internally generated indexes.
 149
 150         <format>html:<xsl:param>index.on.type=1 # = 1 For the native stylesheets to generate multiple different indexes.
 151
 152         <auto-index-script>circular_buffer.idx # Specifies the name of the script to load for circular_buffer.
 153         <auto-index-prefix>../../.. # Will get you back up to /circular_buffer, so !scan-path "boost/circular_buffer/" is where *.hpp will be,
 154         # and /libs/circular_buffer for other files.
 155         # Without this would need !scan-path "../../../boost/circular_buffer"
 156
 157         # Used by Quickbook to invoke indexing.
 158     # Required by boost-trunk/doc/ see jamfile.v2 to use auto-index.
 159     # Choose indexing method for html:
 160     <format>html:<auto-index-internal>on
 161     <format>docbook:<auto-index-internal>on
 162
 163     # PDF Options:
 164     # ============
 165     # TOC Generation: this is needed for FOP-0.9 and later:
 166     <format>pdf:<xsl:param>fop1.extensions=0
 167     # Or enable this if you're using XEP:
 168     <format>pdf:<xsl:param>xep.extensions=1
 169     # TOC generation: this is needed for FOP 0.2, but must not be set to zero for FOP-0.9!
 170     <format>pdf:<xsl:param>fop.extensions=0
 171     # No indent on body text:
 172     <xsl:param>body.start.indent=0pt
 173     # Margin size:
 174     <xsl:param>page.margin.inner=0.5in
 175     # Margin size:
 176     <xsl:param>page.margin.outer=0.5in
 177
 178     # Yes, we want graphics for admonishments:
 179     <xsl:param>admon.graphics=1
 180
 181     # Set these one for PDF generation *only*:
 182     # default png graphics are awful in PDF form,
 183     # better use SVG instead:
 184     <format>pdf:<xsl:param>admon.graphics.extension=".svg"
 185     #<format>pdf:<xsl:param>admon.graphics.extension=".png" # Only png images are available.
 186     # Don't need this, default path works OK:
 187     #<format>pdf:<xsl:param>admon.graphics.path=$(nav_images)/ # next, prev, note, tip ... for pdf.
 188     <format>pdf:<xsl:param>use.role.for.mediaobject=1
 189     <format>pdf:<xsl:param>preferred.mediaobject.role=print
 190     <format>pdf:<xsl:param>img.src.path=$(pdf_images_location)/ # graphics (diagrams) for pdf.
 191     <format>pdf:<xsl:param>draft.mode="no"
 192     <format>pdf:<xsl:param>boost.url.prefix=../../../..
 193
 194     <dependency>autodoc #
 195     <dependency>png_install
 196    ;
 197
 198 # Install (copy) the 'master' copies of all icon images (both PNG and SVG)
 199 # and the Boost logo from your current Boost-root
 200 # to the local /doc/html/images folder so that html is complete and standalone.
 201 install png_install : [ glob $(here)/*.png ] : <location>$(here)/../../../doc/html/images ;
 202
 203 # install pdf-install : standalone : <install-type>PDF <location>. ;
 204 # Effectively copies the file from \bin folder to the \doc folder,
 205 # but will not work as expected if doxygen and/or autoindex is used
 206 # because a modified pdf file is created, so this command
 207 # will rename the file to the expected filename, here circular_buffer.pdf.
 208
 209 install pdfinstall : standalone : <install-type>PDF <location>. <name>circular_buffer.pdf ;
 210
 211 ###############################################################################
 212 alias boostdoc
 213     : standalone/<format>docbook
 214     :
 215     :
 216     : ;
 217 explicit boostdoc ;
 218 alias boostrelease ;
 219 explicit boostrelease ;