Bug 1310: Need to commit changes in doc/doxygen as well, of course ;-)

doc/doxygen/CMakeLists.txt

+# $Id$
+
+#set(DOXYGEN_HTML_OUTPUT "${CMAKE_BINARY_DIR}/doc/html/doxygen")
+#file(MAKE_DIRECTORY "${CMAKE_BINARY_DIR}/doc/html/doxygen")
+
+configure_file(
+  "${CMAKE_CURRENT_SOURCE_DIR}/quick-guide.cfg.in"
+  "${CMAKE_CURRENT_BINARY_DIR}/quick-guide.cfg" @ONLY)
+
+configure_file(
+  "${CMAKE_SOURCE_DIR}/CMake/docscripts/MakeDoxyDoc.cmake.in"
+  "${CMAKE_CURRENT_BINARY_DIR}/MakeDoxyDoc.cmake" @ONLY)
+
+add_custom_target(doxygen_quick_guide
+  COMMAND "${CMAKE_COMMAND}" 
+  -D DOXYGEN_CONFIG_FILE="${CMAKE_CURRENT_BINARY_DIR}/quick-guide.cfg"
+  -D DOXYGEN_OUTPUT_LOG_FILE="${CMAKE_CURRENT_BINARY_DIR}/quick-guide.log"
+  -P "${CMAKE_CURRENT_BINARY_DIR}/MakeDoxyDoc.cmake"
+#  DEPENDS quick-guide.dox
+#  WORKING_DIRECTORY "${DOXYGEN_OUTPUT_DIRECTORY}"
+  WORKING_DIRECTORY "${CMAKE_CURRENT_SOURCE_DIR}"
+  COMMENT "Generating Doxygen Quick Guide ... \n       (see doxygen_quick_guide.log for details)")
+
+add_subdirectory(examples)

doc/doxygen/Makefile

-#
-# Makefile for the Doxygen Quick Guide.
-#
-
-# Set variables if they are undefined
-export LOFAR   ?= $(shell pwd | sed 's|/LOFAR/.*|/LOFAR|')
-export DOXYGEN ?= /usr/bin/doxygen
-export DOCDIR  ?= $(LOFAR)/doc/html
-
-# Add this documentation to the "doxygen" subdirectory.
-THISDOCDIR := $(DOCDIR)/doxygen
-
-doc:
-	@if ! [ -d $(THISDOCDIR) ]; then mkdir $(THISDOCDIR); fi
-	@cp quick-guide.cfg doxygen.cfg
-	@echo "HTML_OUTPUT = $(THISDOCDIR)" >> doxygen.cfg
-	@echo "GENERATE_TAGFILE = $(DOCDIR)/doxygen.tag" >> doxygen.cfg
-	$(DOXYGEN) doxygen.cfg
-	$(MAKE) doc -C examples
-
-clean:
-	$(RM) -r $(THISDOCDIR) $(DOCDIR)/doxygen.tag doxygen.cfg
-	$(MAKE) clean -C examples
-

doc/doxygen/examples/CMakeLists.txt

+add_custom_target(dqg_example_group
+  COMMAND ${CMAKE_COMMAND} -E
+    make_directory "${CMAKE_BINARY_DIR}/doc/html/doxygen/examples/group"
+  COMMAND ${DOXYGEN_EXECUTABLE} ${CMAKE_CURRENT_BINARY_DIR}/group.cfg)
+
+add_custom_target(dqg_example_memgrp
+  COMMAND ${CMAKE_COMMAND} -E
+    make_directory "${CMAKE_BINARY_DIR}/doc/html/doxygen/examples/memgrp"
+  COMMAND ${DOXYGEN_EXECUTABLE} ${CMAKE_CURRENT_BINARY_DIR}/memgrp.cfg)
+
+configure_file(
+  ${CMAKE_CURRENT_SOURCE_DIR}/group.cfg
+  ${CMAKE_CURRENT_BINARY_DIR}/group.cfg
+  @ONLY)
+
+configure_file(
+  ${CMAKE_CURRENT_SOURCE_DIR}/memgrp.cfg
+  ${CMAKE_CURRENT_BINARY_DIR}/memgrp.cfg
+  @ONLY)

doc/doxygen/examples/Makefile

-#
-# Makefile for the examples that accompany the Doxygen Quick Guide.
-#
-
-# Set variables if they are undefined
-export LOFAR   ?= $(shell pwd | sed 's|/LOFAR/.*|/LOFAR|')
-export DOXYGEN ?= /usr/bin/doxygen
-export DOCDIR  ?= $(LOFAR)/doc/html
-
-# Add this documentation to the "doxygen/examples" subdirectory.
-THISDOCDIR := $(DOCDIR)/doxygen/examples
-
-doc: $(THISDOCDIR)/group/index.html \
-     $(THISDOCDIR)/memgrp/index.html
-
-clean:
-	$(RM) -r $(THISDOCDIR) doxygen.cfg
-
-$(THISDOCDIR)/group/index.html: group.h group.cfg
-	@if ! [ -d $(THISDOCDIR) ]; then mkdir $(THISDOCDIR); fi
-	@cp group.cfg doxygen.cfg
-	@echo "HTML_OUTPUT          = $(THISDOCDIR)/group" >> doxygen.cfg
-	$(DOXYGEN) doxygen.cfg
-
-$(THISDOCDIR)/memgrp/index.html: memgrp.h memgrp.cfg
-	@if ! [ -d $(THISDOCDIR) ]; then mkdir $(THISDOCDIR); fi
-	@cp memgrp.cfg doxygen.cfg
-	@echo "HTML_OUTPUT          = $(THISDOCDIR)/memgrp" >> doxygen.cfg
-	$(DOXYGEN) doxygen.cfg

doc/doxygen/examples/group.cfg → doc/doxygen/examples/group.cfg.in

@@ -3,10 +3,10 @@ GENERATE_LATEX       = NO
 GENERATE_MAN         = NO
 GENERATE_RTF         = NO
 CASE_SENSE_NAMES     = NO
-INPUT                = group.h
+INPUT                = "@CMAKE_CURRENT_SOURCE_DIR@/group.h"
+HTML_OUTPUT          = "@CMAKE_BINARY_DIR@/doc/html/doxygen/examples/group"
 QUIET                = YES
 DISTRIBUTE_GROUP_DOC = YES
 JAVADOC_AUTOBRIEF    = YES
-INPUT_FILTER         = $(LOFAR)/autoconf_share/slash2spanning.pl
+INPUT_FILTER         = "@CMAKE_SOURCE_DIR@/CMake/docscripts/slash2spanning.pl"
 FILTER_SOURCE_FILES  = YES
-

doc/doxygen/examples/memgrp.cfg → doc/doxygen/examples/memgrp.cfg.in

@@ -3,9 +3,10 @@ GENERATE_LATEX       = NO
 GENERATE_MAN         = NO
 GENERATE_RTF         = NO
 CASE_SENSE_NAMES     = NO
-INPUT                = memgrp.h
+INPUT                = "@CMAKE_CURRENT_SOURCE_DIR@/memgrp.h"
+HTML_OUTPUT          = "@CMAKE_BINARY_DIR@/doc/html/doxygen/examples/memgrp"
 QUIET                = YES
 DISTRIBUTE_GROUP_DOC = YES
 JAVADOC_AUTOBRIEF    = YES
-INPUT_FILTER         = $(LOFAR)/autoconf_share/slash2spanning.pl
+INPUT_FILTER         = "@CMAKE_SOURCE_DIR@/CMake/docscripts/slash2spanning.pl"
 FILTER_SOURCE_FILES  = YES

doc/doxygen/pkgdoc-howto.cfg

-OUTPUT_DIRECTORY     = .
-OUTPUT_LANGUAGE      = dutch
-HTML_OUTPUT          = html
-INPUT                = pkgdoc-howto.doc
-GENERATE_LATEX       = NO

doc/doxygen/pkgdoc-howto.dox

-/**
-
-\page pkgdoc-howto LOFAR Package Documentatie: Hoe?
-\author Marcel Loose
-\date 26 januari 2005
-
-\anchor pkgdoc-toc
-<dl>
-<dt><b>Inhoud:</b></dt>
-<dd>
-  \ref pkgdoc-intro <br>
-  \ref pkgdoc-apart <br>
-  \ref pkgdoc-perpkg <br>
-  \ref pkgdoc-module <br>
-  \ref pkgdoc-conc <br>
-</dd>
-</dl>
-
-<hr>
-
-\section pkgdoc-intro Introductie
-
-Ik heb de afgelopen dagen uitgebreid onderzocht wat de beste methode is om de
-diverse LOFAR packages te documenteren en deze documentatie te integreren met
-de door Doxygen gegenereerde HTML pagina's. Er is een aantal manieren waarop
-integratie kan plaatsvinden. Ik zal er drie hieronder beschrijven.
-
-\ref pkgdoc-toc "[Inhoud]"
-<hr>
-
-\section pkgdoc-apart Aparte documentatie van packages
-
-Bij deze methode worden packages geheel onafhankelijk van de feitelijke source
-code documentatie beschreven. Doxygen biedt de mogelijkheid om dergelijke
-pagina's te maken m.b.v. structuurcommando's als \c \\page, \c \\section, \c
-\\subsection, etc. Het is ook mogelijk om referenties naar dergelijke pagina's
-en (sub)secties op te nemen.
-
-Helaas is het niet eenvoudig om een referentie naar de source-code
-documentatie van een package op te nemen. De belangrijkste reden hiervoor is
-dat het begrip \e package, zoals we dat binnen LOFAR kennen, niet
-&eacute;&eacute;n-op-&eacute;&eacute;n overeenkomt met de structuur in de
-source code; een LOFAR package is in feite een collectie van sources waarvan
-de object-code samengevoegd wordt in een software-bibliotheek. Hierdoor
-bestaat er geen `ingang' voor een package; er is geen HTML file waarnaar
-gelinkt zou kunnen worden.
-
-Doxygen kent weliswaar het begrip \e package, maar hiermee wordt dan een
-Java package bedoeld. De C++ `equivalent' hiervan is de \e namespace. Het
-moge duidelijk zijn dat de onderverdeling van LOFAR packages op dit moment in
-het geheel niet matcht met de gebruikte namespaces.
-
-
-<b>Voordelen</b>
-- De bestaande documentatie in de \c *.h files hoeft niet aangepast of
-  uitgebreid te worden. De beschrijving van packages is feitelijk gescheiden
-  van de beschrijving van de source code. (Dit is tevens een nadeel).
-
-<b>Nadelen</b>
-- De beschrijving van packages is teveel gescheiden van de beschrijving van de
-  bijbehorende source code. In feite is een `package' niets meer dan een
-  fysieke bundeling van de afzonderlijke object-files in een component (een
-  software bibliotheek).
-
-<b>Oplossingen</b>
-- De sources van ieder package zouden in een aparte namespace geplaatst moeten
-  worden. Hoewel dit een richtlijn is in de nieuwe, nog uit te brengen,
-  <em>C++ Coding Standard</em> is de praktijk anders. Toch is deze oplossing
-  niet volledig, omdat de nieuwe standaard voorschrijft dat ieder package in
-  de namespace \c LOFAR geplaatst moeten worden; packages worden dus niet
-  genest!
-
-\ref pkgdoc-toc "[Inhoud]"
-<hr>
-
-
-\section pkgdoc-perpkg Links naar `per package' Doxygen documentatie
-
-Bij deze methode ga je er vanuit dat ieder package afzonderlijk wordt
-ge-doxygen-d; dit is bijvoorbeeld het geval als je als ontwikkelaar een
-<tt>make doc</tt> doet in je eigen build directory. Je kunt Doxygen een
-zogenaamde <em>tag file</em> laten genereren. Je kunt vervolgens een globale
-LOFAR documentie pagina maken m.b.v. deze tag files. Feitelijk is deze methode
-bedoeld om de documentatie van third-party producten beter te kunnen
-integreren in je eigen documentatie.
-
-
-<b>Voordelen</b>
-- De bestaande documentatie in de <tt>*.h</tt> files hoeft niet aangepast te
-  worden.
-- Je kunt vanuit een willekeurige pagina eenvoudig linken naar een bepaald
-  package, omdat ieder package een eigen \c index.html en \c main.html file
-  heeft.
-- Alleen gewijzigde packages hoeven opnieuwe ge-doxygen-d te worden.
-
-<b>Nadelen</b>
-- De documentatie pagina's missen de benodigde samenhang. Ieder package
-  heeft namelijk zijn eigen `Main Page'. Je raakt hierdoor al snel het spoor
-  bijster.
-- In het algemeen is het navigeren lastiger, omdat je niet kunt linken
-  naar de `echte' hoofdpagina. Je kunt hier dan feitelijk alleen nog maar naar
-  terug m.b.v. de `Back' button.
-
-<b>Oplossingen</b>
-- Er is eigenlijk niet echt een oplossing voor het hierboven beschreven
-  probleem. De documentatie wordt namelijk in fragmenten gegenereerd. Het is
-  vervolgens erg lastig om hier weer een samenhangend geheel te maken.
-
-\ref pkgdoc-toc "[Inhoud]"
-<hr>
-
-
-\section pkgdoc-module Packages als Doxygen `modules'
-
-Bij deze methode wordt gebruik gemaakt van het \e Grouping mechanisme in
-Doxygen. Met behulp van \e Grouping is het mogelijk om een hi&euml;rachische
-\e view van zogenaamde \e modules op je project te cre&euml;eren. Hiervoor
-zijn de commando's \c \\defgroup, \c \\ingroup en \c \\addtogroup beschikbaar.
-
-
-\e Grouping is naar mijn idee &eacute;&eacute;n van de slechtst begrepen
-faciliteiten binnen Doxygen. De gebruikershandleiding is onduidelijk over \e
-hoe je `grouping' het beste kunt gebruiken. Een korte blik op <a
-href="http://www.stack.nl/~dimitri/doxygen/projects.html">voorbeeldprojecten</a>
-op de Doxygen site laat zien dat \e grouping op de meest uiteenlopende
-manieren wordt gebruikt.
-
-We zouden ervoor kunnen kiezen om de afzonderlijke LOFAR packages te
-documenteren in groepen. Omdat groepen genest kunnen worden, past dit goed
-op de hi&euml;rachische structuur van packages. 
-
-<b>Voordelen</b>
-- Het is eenvoudig om een hyperlink op te nemen naar de beschrijving van een
-  package, omdat Doxygen voor iedere \e module een aparte HTML file genereert.
-- Ook zogenaamde top-level packages, zoals CEP, kunnen worden gedocumenteerd.
-  Dit in tegenstelling tot de oplossing die genoemd wordt bij de
-  \ref pkgdoc-apart "eerste methode".
-
-<b>Nadelen</b>
-- De documentatie in alle bestaande <tt>*.h</tt> files moet worden aangepast.
-- Het is noodzakelijk dat er consci&euml;ntieus omgegaan wordt met het
-  toevoegen van de commando's \c \\defgroup, \c \\ingroup en \c
-  \\addtogroup. Helaas is dit nauwelijks te automatiseren en dus foutgevoelig.
-
-<b>Oplossingen</b>
-- Het is (deels) mogelijk om de software-ontwikkelaars te helpen door
-  zogenaamde sjablonen (\e templates) beschikbaar te stellen voor
-  bijv. <tt>*.h</tt> files, <tt>*.cc</tt> files, etc. Hierin zouden \e
-  placeholders opgenomen kunnen worden (bijv. \c $package$ en \c $class$) die
-  door een extern script automatisch juist ingevuld worden. Wellicht kan het
-  TMS project hierbij als voorbeeld dienen.
-
-\ref pkgdoc-toc "[Inhoud]"
-<hr>
-
-
-\section pkgdoc-conc Conclusies
-
-Als we de voor- en nadelen van de hierboven beschreven mogelijkheden bekijken
-dan kunnen we de voorzichtige conclusie trekken dat het wellicht het beste is
-(vanuit oogpunt van overzichtelijke documentatie) om te kiezen voor de laatst
-beschreven aanpak; om packages als \ref pkgdoc-module "Doxygen `modules'" te
-beschrijven. 
-
-Hoewel deze aanpak op de korte termijn nogal wat werk met zich meebrengt, werk
-dat \e niet eenvoudig met behulp van een script uitgevoerd kan worden, is dit
-mijns inziens wel de beste oplossing voor de lange termijn. We zullen nog wel
-moeten zoeken naar oplossingen om de juiste \e grouping commando's zoveel
-mogelijk automatisch te laten genereren, opdat fouten zoveel mogelijk worden
-voorkomen.
-
-\ref pkgdoc-toc "[Inhoud]"
-
-*/

doc/doxygen/quick-guide.cfg → doc/doxygen/quick-guide.cfg.in

-OUTPUT_DIRECTORY     = .
+HTML_OUTPUT          = "@DOXYGEN_HTML_OUTPUT@/doxygen"
 INPUT                = quick-guide.dox
 EXAMPLE_PATH         = examples
 GENERATE_LATEX       = NO
+GENERATE_TAGFILE     = "@DOXYGEN_HTML_OUTPUT@/quick-guide.tag"