Generating and Improving Documentation

Introduction

If you think that the documentation of Boost.Geometry could be improved and are willing to help, this tutorial is for you.

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/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.

Building documentation

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

cd libs/geometry/doc

Execute make_qbk.py python script (calling doxygen, doxygen_xml2qbk and b2) e.g. running

python make_qbk.py

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. It's also wise to consult the changes on the list beforehand since someone might be already working on them.