Boost C++ Libraries

It is considerate to make the use of auto-index optional in Boost.Build, to allow users who do not have AutoIndex installed to still be able to build your documentation.

This also very convenient while you are refining your documentation, to allow you to decide to build indexes, or not: building indexes can take long time, if you are just correcting typos, you won't want to wait while you keep rebuilding the index!

One method of setting up optional AutoIndex support is to place all AutoIndex configuration in a the body of a bjam if statement:

if --enable-index in  [ modules.peek : ARGV ]
  {
     ECHO "Building the  docs with automatic index generation enabled." ;

     using auto-index ;
     project : requirements
          <auto-index>on
          <auto-index-script>index.idx

           ... other AutoIndex options here...

        # And tell Quickbook that it should enable indexing.
        <quickbook-define>enable_index
    ;
  }
  else
  {
     ECHO "Building the my_library docs with automatic index generation disabled. To get an Index, try building with --enable-index." ;
  }

You will also need to add a conditional statement at the end of your Quickbook file, so that the index(es) is/are only added after the last section if indexing is enabled.

[? enable_index
'''
  <index/>
'''
]

To use this jamfile, you need to cd to your docs folder, for example:

cd \boost-sandbox\guild\mylibrary\libs\mylibrary\doc

and then run bjam to build the docs without index, for example:

bjam -a html > mylibrary_html.log

or with index(es)

bjam -a html --enable-index > mylibrary_html_index.log