mirror of https://github.com/CGAL/cgal
86 lines
2.8 KiB
Plaintext
86 lines
2.8 KiB
Plaintext
# 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 build 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
|
|
PkgDescBegin and PkgDescEnd 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.
|