Skip to content

Building the Documentation

Jump to bottom Edit New page
Mael Rouxel-Labbé edited this page Mar 28, 2024 · 1 revision

Table of Contents

Getting and Installing the Tools

To build the CGAL documentation, we use two tools. In the following documentation, we use /path/to/branch to refer to the path where you have a checkout of your git branch on your disk.

doxygen

doxygen generates documentation for individual CGAL packages. We have added a few features and fixes to doxygen, which we communicate to its author to get them included upstream. The official documentation is built with this patched version while all the patches are not integrated in the official release. You may try it if you wish (see https://github.com/CGAL/doxygen), but it is not required to build a correct version of your documentation. A windows executable is available here.

  • doxygen 1.8.13 works almost well. This branch contains the patch for having less output when EXTRACT_ALL=ON.

  • doxygen 1.8.11 (+1.8.12) generates an incomplete website: the treeview is missing. Maybe our hackery is incompatible? Also too many things are exported in tags. Only two consecutive runs doxygen can be done. After that the tag files must be deleted to avoid many warnings.

  • doxygen 1.8.10 generates an incomplete website: the treeview is missing.

  • doxygen 1.8.8 gives a segmentation fault.

  • doxygen 1.8.5 has a bug and cannot build correctly the target BGL_doc after some tag files exists (it will fill the memory before crashing).

The only remaining extra patch corresponds to this bug report: 502d15f Bug 684978 - EXTRACT_ALL creates superfluous detail sections. See also this PR.

There is also the current bug report about a blocking issue found in the 1.8.12 version.

Syntax Highlighting

  • Microsoft provides a plugin for Visual Studio for syntax highlighting.
  • On Emacs there is doxymacs.

MathJax

MathJax is required to be installed if you need to have typeset formulas without an internet connection.

  • get MathJax: git clone git://github.com/mathjax/MathJax.git /path/to/MathJax
  • to configure the documentation to build with your local MathJax, change the CMake variable CGAL_DOC_MATHJAX_LOCATION to point to your locale MathJax

Note:

  • For alternative methods to get MathJax, see here.
  • You have the possibility to disable MathJax and use fixed size bitmap by setting USE_MATHJAX = NO in the config file /path/to/branch/Documentation/BaseDoxyfile.in.

Building The Documentation

To build the documentation on Unix:

cd /path/to/cgal/build/dir
cmake -DBUILD_DOC:BOOL=ON /path/to/cgal/ # if not already done
make doc

Alternatively, if your branch is fresh enough and contains commit 96c64d48 (merge of PR #1444), you can directly call cmake on the doc CMakeLists.txt, which will skip the CGAL configuration steps

cd /path/to/cgal/build/dir
cmake /path/to/cgal/Documentation/doc # if you use a CGAL branch
# or
cmake /path/to/cgal/doc # if you use a CGAL release
make doc

If make does not find target "doc", it is probably because your branch is too old. Try: make Documentation_doc.

To build the documentation with Visual Studio, build the doc target in Visual Studio.

The CMake variable CGAL_DOC_CREATE_LOGS allows for more detailed logs in the folder (doc_log) which shows warnings and errors that may not be shown when building the documentation inside Visual Studio.

With a self-built doxygen, or with doxygen from MacPorts (/opt/local/bin/doxygen) you will probably need to adjust the CMake variable DOXYGEN_EXECUTABLE to point to the right location.

After that, a single run suffices.

This will generate the output for each package and a master package with the Introduction, Preliminaries, and Installation manuals and a complete index.

Building Only a Single Package

Often you only want to work on one package and building the whole documentation would take longer than you would like. To do this:

# in /path/to/cgal/build/dir
make My_package_doc

in Visual Studio build the target My_package_doc.

Doing this requires that the doc target has been built twice before.

In case you are working on a new package, make sure that you followed the steps discussed here.

Looking at the Result

The result will be stored in /path/to/cgal/build/dir/doc_output/. The main entry point is: /path/to/cgal/build/dir/doc_output/Manual/index.html. The documentation of a respective package can be found under /path/to/cgal/build/dir/doc_output/My_package/index.html.

Html output postprocessing: html_output_post_processing.py

The postprocessing of the html output is triggered by building the target doc_with_postprocessing:

# in /path/to/cgal/build/dir
make doc_with_postprocessing

Internally, the script html_output_post_processing.py is used to do some output cleaning in the html output of doxygen. This script:

  • turns specific classes into concepts.
  • performs some scrubbing of the documentation to remove duplicate files, small glitches and the like.
  • uses special icons in Concept and class list pages.
  • numbers the figures using CGAL doxygen macros.

This script requires at least Python 2 and the library PyQuery, and python-lxml v2.3.2 (or higher). To check which python executable is used, you can check in your CMakeCache.txt the value of PYTHON_EXECUTABLE.

Note that pip is a solution to install python dependencies on machine you do not administrate.

Getting it to work on Windows

Using PIP

Getting the postprocessing working on Windows, we have not checked with pip yet, but we used easy_install instead.

  • The recommended way to install setuptools on Windows is to download ez_setup.py and run it. The script will download the appropriate .egg file and install it for you. 1 2
  • Install the C++ libraries libxml and libxslt. As written on 3 Igor Zlatkovic is now the maintainer of the Windows port, he provides binaries. 4
  • Add in PATH C:\Python27, C:\Python27\Scripts, and the bin directory of libxml/libxslt
  • In a cmd.exe
    • run easy_install lxml==2.3 to install the python bindings of libxml (the version is fixed to 2.3 as it is broken for the latest version)
    • run easy_install pyquery to install the pyquery package

To check that everything is fine, you can run in a cmd

> python
>>> import lxml
>>> import pyquery

Testing the Documentation

To create a small HTML overview detailing errors and warnings when building the documentation use:

cd /path/to/cgal/build/dir
cmake -DBUILD_DOC:BOOL=ON -DCGAL_DOC_CREATE_LOGS:BOOL=TRUE /path/to/cgal/
make doc_and_publish_testsuite

Releasing the Documentation

Use cmake -DBUILD_DOC:BOOL=ON -DCGAL_DOC_RELEASE:BOOL=TRUE .. -DCGAL_DOC_MATHJAX_LOCATION:STRING=../../MathJax if you intend to make public the documentation.

  • The flag CGAL_DOC_RELEASE removes TODO-list, bug-list,...
  • The path related to MathJax indicates the relative location from a package directory (for example https://doc.cgal.org/4.3/Kernel_23/, or doc_output/Manual in your local build) to a local MathJax checkout on the server. This is required in particular when using https. Modern browsers protect users by disabling any http (like MathJax CDN) included in a https page.

Changing things

The file Documentation/Customizations.txt contains a detailed list of the customizations that are applied to doxygen. It should be maintained if things are changed.

Building The Documentation in a Pull Request

If you are a member of the CGAL project, you can use GitHub Actions to generate documentation directly within a GitHub pull request. See this page for more information.

Home > Developer Resources > Doxygen Guidelines

Home

General Information

Developer Resources

Maintainer Resources

Clone this wiki locally