Generating and Improving Documentation

Table of Contents

• Introduction
• Generating documentation
  • Prerequesites
  • Preparation
  • Building documentation
• Improving documentation

Introduction

Boost.Geometry documentation is generated using Boost.QuickBook which is a WikiWiki style documentation tool. The logical structure of documentation is described in text files using markup language. Then e.g. html or pdf documentation can be generated. More information can be found here: (Boost.QuickBook)

In this tutorial we'll focus on generating html documentation, e.g. available at the official webpage (Boost.Geometry documentation).

Generating documentation

Prerequesites

• "working" Boost
  • checked out from repository (TryModBoost) or downloaded from the webpage.
  • b2 generated by bootstrap script (Getting Started)
• a compiler - gcc, clang, Visual Studio Express, etc.

Note that if you're thinking about contributing you should probably also check out the Contribution Tutorial. This way you'd be able to work on the development version of the documentation and propose changes directly on GitHub.

Preparation

Install required programs/libraries and configure Boost

• Install doxygen
• Install python
• Install and configure QuickBook by following: Quickbook Installation. Tip: create user-config.jam file in your user home directory if needed.

Compile doxygen_xml2qbk tool shipped with Boost.Geometry. Assuming you're in Boost root directory (below as BOOST_ROOT) call

./b2 libs/geometry/doc/src/docutils/tools/doxygen_xml2qbk

The compiled tool should be placed in BOOST_ROOT/dist/bin directory.

Make sure that you can call all of the above programs from any directory, including doxygen_xml2qbk and b2. If needed add Boost root directory and BOOST_ROOT/dist/bin to PATH environment variable.

Building documentation

Enter the directory containing Boost.Geometry documentation (assuming you were in BOOST_ROOT)

cd libs/geometry/doc

Execute b2 (running make_qbk.py python script calling doxygen, doxygen_xml2qbk). Note that at this point BOOST_ROOT and BOOST_ROOT/dist/bin should've been added to PATH environment variable.

b2

The resulting documentation should be generated in BOOST_ROOT/libs/geometry/doc/html directory.

Improving documentation

The documentation files can be found in the BOOST_ROOT/libs/geometry/doc directory. Sections like Introduction, Quick Start, etc. can be found there as QBK files. The reference on the other hand is generated automatically with doxygen and doxygen_xml2qbk, so to improve the description of algorithms it'd be required to modify the source files.

If you had any problems or questions, please ask on the mailing list. Furthermore it'd be wise to consult the changes on the list beforehand since someone might already be working on the same or similar thing.