Changes between Version 8 and Version 9 of pm-doxygen


Ignore:
Timestamp:
Mar 29, 2015 2:33:49 PM (6 years ago)
Author:
tkr
Comment:

--

Legend:

Unmodified
Added
Removed
Modified
  • pm-doxygen

    v8 v9  
    11= Using Doxygen in COIN-OR =
    22
    3 COIN-OR has chosen to use the [http://www.stack.nl/~dimitri/doxygen/ doxygen] program for in-code documentation. Briefly, documentation is generated by scanning source files (by default, only {{{.h}}} and {{{.hpp}}} files) which have been annotated with comments and doxygen markup. As an example, here's the [http://www.coin-or.org/Doxygen/Osi/index.html doxygen documentation generated for Osi]. Complete [http://www.stack.nl/~dimitri/doxygen/manual.html on-line doxygen documentation] is available there.
     3COIN-OR has chosen to make the [http://www.stack.nl/~dimitri/doxygen/ Doxygen] program for in-code documentation our standard documentation system. Support for generating documentation using [http://www.stack.nl/~dimitri/doxygen/ Doxygen] is provided automatically as part of the standard build harness if you follow these guidelines. Briefly, documentation is generated by scanning source files (by default, only {{{.h}}} and {{{.hpp}}} files) which have been annotated with comments and doxygen markup. As an example, here's the [http://www.coin-or.org/Doxygen/Osi/index.html doxygen documentation generated for Osi]. Complete [http://www.stack.nl/~dimitri/doxygen/manual.html on-line doxygen documentation] is available there.
    44
    55Doxygen documentation can be built and installed just as the code is built and installed. Doxygen documentation for a given project or package can be linked with doxygen documentation for other projects or packages, within the limits of doxygen's ability.
    66
    7 '''NOTE''': This page describes the new architecture for generating doxygen documentation. It is only available when you use the !BuildTools >= 0.6. If your project is already set up under the old architecture, you will be replacing the existing {{{doxygen.conf}}} configuration file. If you've customized it, save it off to the side so you can restore the customizations after conversion.
     7'''NOTE''': This page describes procedures for generating doxygen documentation available with !BuildTools >= 0.8. Most of what is written here is also valid for !BuildTools >= 0.6.
    88
    99To use doxygen within the COIN-OR build system, you should first document your code using doxygen markup. Doxygen markup is designed to be minimally intrusive and works well with common styles of in-code documentation. Even with zero markup, doxygen will still generate minimal documentation showing classes and structures, their members, and their interrelationships (''e.g.'', [http://www.coin-or.org/Doxygen/DyLP DyLP]). Consult the source code for any of the COIN-OR projects that have documentation [http://www.coin-or.org/Doxygen here].
     
    1212Replace 'Osi' with the name of your project. Consult the various files referenced below for examples.
    1313
    14 === Step 1: Install {{{doxygen.conf.in}}} ===
    15 The next step is to add doxygen configuration files (by default, {{{doxygen.conf}}}) to control the documentation that doxygen produces. As with many other files, these are customized by the {{{configure}}} script, so you're really adding {{{doxygen.conf.in}}}. You'll have two of these, one at the top level of the project's package, {{{Osi/doxydoc/doxygen.conf.in}}}, and one in the project's main directory, {{{Osi/Osi/doxydoc/doxygen.conf.in}}}.
     14== Setting Up ==
    1615
    17 Why two? The short answer is flexibility. Traditionally, the COIN-OR package for a project has been assembled by specifying dependencies as externals. {{{Osi/doxydoc/doxygen.conf.in}}} will be used only with the Osi package. {{{Osi/Osi/doxydoc/doxygen.conf.in}}} will be used whenever some other project uses Osi as an external. If you wish, you can exploit this, adjusting the package-level {{{doxygen.conf.in}}} to produce additional documentation appropriate for the package but not necessary when the code is being used as an external.
     16These steps have already been completed for most projects that use the common build system, so if you are just attempting to generate documentation, please skip to the section on building and installing.
    1817
    19 Where can you get the package and project {{{doxygen.conf.in}}} files? The best approach is to grab them from a project that's already set up, just to ensure that you have the most current version. For convenience, however, vanilla [attachment:doxygen.conf.in.pkg package] and [attachment:doxygen.conf.in.proj project] configuration files are attached to this page. There are only two differences:
     18=== Step 1: Add {{{doxygen.conf.in}}} to repository ===
     19The first step in setting things up is to add doxygen configuration files in the proper places in order to control the documentation that doxygen produces. As with many other files, these configuration files are customized and automatically generated by the {{{configure}}} script, so you're going to be adding autoconf files named {{{doxygen.conf.in}}} to your repository. You'll have either one or two of these, depending on your desired usage. The first will be at the top level of the project's package, {{{Osi/doxydoc/doxygen.conf.in}}} (this one is optional), and the second will be in the project's main directory, {{{Osi/Osi/doxydoc/doxygen.conf.in}}}. The former configuration file can be used to build a monolithic documentation package including all dependencies in a single documentation package. The second is used to build documentation just for the package itself, treating other packages as externals. If you're starting from scratch, you can get samples of the {{{doxygen.conf.in}}} files from another project that is already set up and modify them, just to ensure that you have the most current version. For convenience, however, vanilla [attachment:doxygen.conf.in.pkg package] and [attachment:doxygen.conf.in.proj project] configuration files are attached to this page. There are only two differences:
    2020 * In the package file, {{{INPUT = @abs_top_srcdir@}}}; in the project file, {{{INPUT = @abs_top_srcdir@/src}}}. Thus the project file will include only the project's base source code. The package file will also pick up unit tests, examples, ''etc.''
    21  * In the package file, {{{EXCLUDE_PATTERNS = */.svn* @coin_doxy_excludes@}}}; in the project file, {{{EXCLUDE_PATTERNS = */.svn*}}}. This allows configuration to exclude the source code of externals, so that it is not processed a second time at the package level. (For technical reasons, the job of ensuring that the project's base source code is not processed twice is handled by {{{Makefile.am}}}. There are some other fine points; consult the macro definition in [source:trunk/coin.m4 coin.m4] if you're interested.)
    22 Be careful to put the package and project files in the correct places!
    23 
    24 '''If you're converting your project from the old style''' of generating doxygen documentation and you've customised {{{Osi/doxydoc/doxygen.conf}}}, transfer any customizations to {{{Osi/doxydoc/doxygen.conf.in}}} or {{{Osi/Osi/doxydoc/doxygen.conf.in}}}, as appropriate.
     21 * In the package file, {{{EXCLUDE_PATTERNS = */.svn* @coin_doxy_excludes@}}}; in the project file, {{{EXCLUDE_PATTERNS = */.svn*}}}. This allows configuration to exclude the source code of externals, so that it is not processed a second time at the package level. (For technical reasons, the job of ensuring that the project's base source code is not processed twice is handled by {{{Makefile.am}}}. There are some other fine points; consult the macro definition in [source:trunk/coin.m4 coin.m4] if you're interested.) Be careful to put the package and project files in the correct places!
    2522
    2623Once you've installed the {{{doxygen.conf.in}}} files, you may wish to adjust them for your project's code. In particular, look at the section titled `Configuration options related to the preprocessor' and consider whether you want to instruct doxygen to consider compilation-time macro definitions.
     
    3128Without this, doxygen would simply see an empty file.
    3229
     30=== Step 2: Modify {{{configure.ac}}} ===
    3331
    34 
    35 === Step 2: Adjust {{{configure.ac}}} ===
    36 
    37 The {{{AC_COIN_DOXYGEN}}} macro is provided to configure doxygen processing. The parameter is a space-separated list of other projects whose doxygen documentation should be linked with the documentation of the current project. For example, the Osi library depends on !CoinUtils, and the project-level {{{configure.ac}}} specifies this dependency as
     32The {{{AC_COIN_DOXYGEN}}} macro is provided to configure doxygen processing and to automatically locate the documentation for any externals. The parameter is a space-separated list of other projects whose doxygen documentation should be linked with the documentation of the current project. For example, the Osi library depends on !CoinUtils, and the project-level {{{configure.ac}}} specifies this dependency as
    3833{{{
    3934AC_COIN_DOXYGEN(CoinUtils)
     
    5247
    5348Configuration sets a number of variables in the {{{doxydoc.conf.in}}} files so that doxygen can locate source code and the tag files that allow linking with other projects' documentation.
    54 There's one other configuration option, {{{--with-dot}}}, which controls doxygen's generation of inheritance and collaboration graphs. This is on by default but somewhat expensive; to disable it specify {{{--without-dot}}} as a configure option. {{{Configure}}} will check for the dot tool (part of the [http://www.graphviz.org graphviz] package) and will disable use of dot if it's not found.
     49There's one other configuration option, {{{--with-dot}}}, which controls doxygen's generation of inheritance and collaboration graphs. This is on by default but somewhat expensive; to disable it specify {{{--without-dot}}} as a configure option. {{{Configure}}} will check for the dot tool (part of the [http://www.graphviz.org graphviz] package) and will disable use of dot if it's not found. It will also look for LaTeX, since that can be used to build PDF documentation.
    5550
    56 === Step 3: Modify {{{Makefile.am}}} ===
     51=== Step 3: Add Targets to {{{Makefile.am}}} (Optional) ===
    5752
    58 The last step is to add the necessary lines to the package- and project-level {{{Makefile.am}}} to build and install the doxygen documentation. Again, the best approach is to go and look at a project that's already set up. But for convenience, here are the relevant portions from the Osi {{{Makefile.am}}} files.
     53This optional step is to add the necessary lines to the package- and project-level {{{Makefile.am}}} to build and install the doxygen documentation. This step is optional beginning with version 0.8.4, since targets for generating doxygen documentation are now automatically added to {{{Makefile.am}}} when including {{{Makemain.inc}}}. If you want to add your own targets, the best approach is to go and look at a project that's already set up. But for convenience, here are the relevant portions from the Osi {{{Makefile.am}}} files.
    5954
    6055In the package-level {{{Makefile.am}}}, add
     
    106101Add {{{doxydoc}}} to the list of {{{.PHONY}}} targets, and add {{{clean-doxydoc}}} to the list of {{{clean-local}}} targets.
    107102
     103== Building and Installing Documentation ==
     104
     105=== Automatically generated targets ===
     106
     107 1. The {{{Makefile}}} in the project's subdirectory has a target {{{doxygen-docs}}} that builds the Doxygen documentation for that project only, treating other projects as externals. Making this target will also create a tags file named {{{doxydoc/xyz_doxy.tags}}} that will be used to link the Doxygen documentation of other projects. There is also a target {{{pdf-doxygen-docs}}} that will build a PDF version of the documentation if that is desired.
     108 1. At configure time, the {{{AC_COIN_DOXYGEN}}} macro tries to locate where the tags files for other projects should be found. If we are doing a monolithic build and the source tree is laid out according to the "classic" repository layout, then we link each project's documentation using the tags fle of other dependent projects in the build directory. If not, we look for the tags files in the the data installation directory (see below for what gets installed where). The links generated in either case, however, are relative, so the documentation should link properly both before and after installation and should be completely portable, as long as all doxydoc directories are moved together.
     109 1. The {{{Makefile}}} in the project root directory has targets {{{all-doxygen-docs}}} and {{{all-pdf-doxygen-docs}}} that will just recursively call the respective commands in each of the subdirectories. As long as the documentation for projects is built in the right order (so that the tags file for each project's dependencies exists when the documentation for that project is built), there is no need for any sort of "monolithic" build of documentation anymore. Everything should work with documentation just as with source---build in the right order and everything links together.
     110
     111=== Installing documentation ===
     112
     113 1. For now, the documentation does not get built and installed as part of {{{make install}}}, since it is a bit of a pain to have the documentation re-built every time a change in the source is made and new binaries are installed.
     114 1. The {{{Makefile}}} in the project's subdirectory has targets {{{install-doxygen-docs}}} and {{{install-all-doxygen-docs}}} that will install all existing documentation (both PDF and HTML) and the tags file in the {{{doxydoc/}}} subdirectory to the documentation install directory ({{{<prefix>/share/coin/doc/Xyz}}} by default).
    108115
    109116
     
    112119
    113120
    114 
    115 
    116 
    117