CGAL 6.2 - Manual: Doxygen for CGAL

CGAL 6.2 - Manual

Loading...
Searching...
No Matches
Doxygen for CGAL

This is the documentation of doxygen hacks that are applied to make the output of Doxygen more suitable to CGAL. It explains the general structure of the build system, the ordinary customizations and the hacks that create what you see.

## Overall structure

## Ordinary Customization

## Hacks

### Package Overview

The package overview is built by having a special command that is filtered by the python script `pkglist_filter.py`.

A command has to be of the form `\package_listing{PKG_NAME}`, where `PKG_NAME` cannot contain a closing `}`.

The command is replaced by the text between the two delimiters `cgalPkgDescriptionBegin` and `cgalPkgDescriptionEnd` in the file `../PKG_NAME/doc/PKG_NAME/PackageDescription.txt`

If `PKG_NAME` is of the form `A/B` the selected file is `../A/doc/B/PackageDescription.txt`. This is to support packages like `TDS_2`, which don't reside in their own packages in the SCM.

### Footnotes

A JQuery footnotes plug-in jquery.footnotes is used to handle footnotes. The special doxygen command `\cgalFootnote` expands to the appropriate html marker. Some JavaScript in `header.html` is used to append the `<ol div="autoFootnotes0">` to the current doc-content div. It is not added to the footer because this would break when tree views are enabled.

The plug-in code is part of `hacks.js` to minimize the amount of files that have to be delivered.

### autotoc

TOCs in HTML are generated by the some JavaScript. This is necessary to work around the fact that doxygen does not supported sections that have no label in a TOC. This command simply becomes a normal toc in LaTex.

### Reference Manual link in the tree view

This hack fiddles with the internal structures and functions of the treeview to remove the unnecessary intermediate top-level module part.

It assigns the first element of the module array (found in `module.js`) to the Reference Manual entry. This makes the tree view link go to that group directly instead of the intermediate link. It also removes one level of nesting.

Unfortunately this changes the overall tree structure. To adjust for that we hijack the `gotoNode` function of `navtree.js` and augment it with an additional check for the specific tree level we borked and redirect it.

All of it is in `header.html` and `hacks.js`.

# Things that would be nice to have

## Search

The search function could be better:

- member functions could be removed
- global functions could be searchable
- package codenames could be supported

## Function Documentation

Automatic grouping of overloads or a switch to document functions in a style more similar to classes, e.g. with their own page.

## Global Build Version

I have no idea how feasible that actually is, but it might be worth a try.

## Package Overview

Build the Package Overview with the help of the Build System.