Changes between Version 3 and Version 4 of pm-doxygen


Ignore:
Timestamp:
Sep 27, 2010 8:51:10 PM (9 years ago)
Author:
lou
Comment:

Add Step 3.

Legend:

Unmodified
Added
Removed
Modified
  • pm-doxygen

    v3 v4  
    1818Why two? The short answer is flexibility. Traditionally, the COIN 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}}} to produce additional documentation appropriate for the package but not necessary when the code is being used as an external.
    1919
    20 Where can you get the package and project {{{doxygen.conf.in}}} files? Again, the best approach is to grab them from a project that's already set up, just to insure that you have the most current version. For convenience, however, vanilla project and package configuration files are attached to this page. There are only two differences:
     20Where 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 insure 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:
    2121 * 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.''
    22  * 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 project's base source code will be processed at both the project and package levels.)
     22 * 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 project's base source code will be processed only at the package level; this is handled by {{{Makefile.am}}}.)
    2323Be careful to put the package and project files in the correct places!
    2424
     
    4848There'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.
    4949
     50=== Step 3: Modify {{{Makefile.am}}} ===
     51
     52The 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.
     53
     54In the package-level {{{Makefile.am}}}, add
     55{{{
     56# Generate doxygen doc'n in subdirectories (except @PACKAGE_NAME@) if a doxydoc
     57# directory is present, then do the base, if present.
     58
     59doxydoc:
     60        for dir in $(subdirs) ; do \
     61          if test $$dir != @PACKAGE_NAME@ && test -r $$dir/doxydoc ; then \
     62            (cd $$dir ; $(MAKE) doxydoc) \
     63          fi ; \
     64        done ; \
     65        if test -r doxydoc/doxygen.conf ; then \
     66          doxygen doxydoc/doxygen.conf ; \
     67        fi
     68
     69clean-doxydoc:
     70        ( cd doxydoc ; rm -rf html *.log *.tag )
     71
     72# DocInstallDir is defined in Makemain.inc and is specific to the package.
     73# For the short term, adopt the notion that we install only the package
     74# doxydoc.
     75
     76install-doxydoc: doxydoc
     77        if test -r doxydoc/doxygen.conf ; then \
     78          $(mkdir_p) $(DocInstallDir) ; \
     79          cp -R doxydoc $(DocInstallDir) ; \
     80        fi
     81
     82uninstall-doxydoc:
     83        rm -rf $(DocInstallDir)/doxydoc
     84
     85clean-local: clean-doxydoc
     86uninstall-local: uninstall-doxydoc
     87}}}
     88Add {{{doxydoc}}} to the list of {{{.PHONY}}} targets.
     89
     90For the project-level {{{Makefile.am}}}, add
     91{{{
     92# Doxygen documentation
     93
     94doxydoc:
     95        doxygen doxydoc/doxygen.conf
     96
     97clean-doxydoc:
     98        ( cd doxydoc ; rm -rf html *.log *.tag )
     99}}}
     100Add {{{doxydoc}}} to the list of {{{.PHONY}}} targets, and add {{{clean-doxydoc}}} to the list of {{{clean-local}}} targets.
    50101
    51102
     
    59110
    60111
    61 
    62 
    63 
    64 
    65 
    66 
    67 
    68 
    69 
    70 
    71 
    72