diff --git a/doc/doxygen/CMakeLists.txt b/doc/doxygen/CMakeLists.txt new file mode 100644 index 0000000000000000000000000000000000000000..6862f9fe1452353ce538aae27706d4a725132be5 --- /dev/null +++ b/doc/doxygen/CMakeLists.txt @@ -0,0 +1,24 @@ +# $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) diff --git a/doc/doxygen/Makefile b/doc/doxygen/Makefile deleted file mode 100644 index cda4853ecafc7778241fafc6d91fe14e4bf6b96b..0000000000000000000000000000000000000000 --- a/doc/doxygen/Makefile +++ /dev/null @@ -1,24 +0,0 @@ -# -# 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 - diff --git a/doc/doxygen/examples/CMakeLists.txt b/doc/doxygen/examples/CMakeLists.txt new file mode 100644 index 0000000000000000000000000000000000000000..702c8b79ae20e0bd0cccf5687adf3ddf46c27803 --- /dev/null +++ b/doc/doxygen/examples/CMakeLists.txt @@ -0,0 +1,19 @@ +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) diff --git a/doc/doxygen/examples/Makefile b/doc/doxygen/examples/Makefile deleted file mode 100644 index 58d18b818d9e2a3f59045ade8189b5f13f83ac13..0000000000000000000000000000000000000000 --- a/doc/doxygen/examples/Makefile +++ /dev/null @@ -1,29 +0,0 @@ -# -# 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 diff --git a/doc/doxygen/examples/group.cfg b/doc/doxygen/examples/group.cfg.in similarity index 53% rename from doc/doxygen/examples/group.cfg rename to doc/doxygen/examples/group.cfg.in index 72efdf3b1f977d02caa260af04bfef17fad2294c..349cc269be64854e234cd00505882cd7f338b6d0 100644 --- a/doc/doxygen/examples/group.cfg +++ b/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 - diff --git a/doc/doxygen/examples/memgrp.cfg b/doc/doxygen/examples/memgrp.cfg.in similarity index 53% rename from doc/doxygen/examples/memgrp.cfg rename to doc/doxygen/examples/memgrp.cfg.in index 9ba2d4a33b059a40b8a734d007aa208cf14bcb8f..81cd70f12b52eb788a50df14c0cec6311126cf69 100644 --- a/doc/doxygen/examples/memgrp.cfg +++ b/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 diff --git a/doc/doxygen/pkgdoc-howto.cfg b/doc/doxygen/pkgdoc-howto.cfg deleted file mode 100644 index 1fc9daea3fac30fbcec57977dc95881bb4dd8f64..0000000000000000000000000000000000000000 --- a/doc/doxygen/pkgdoc-howto.cfg +++ /dev/null @@ -1,5 +0,0 @@ -OUTPUT_DIRECTORY = . -OUTPUT_LANGUAGE = dutch -HTML_OUTPUT = html -INPUT = pkgdoc-howto.doc -GENERATE_LATEX = NO diff --git a/doc/doxygen/pkgdoc-howto.dox b/doc/doxygen/pkgdoc-howto.dox deleted file mode 100644 index 30fcb1672d9076a8804432cf99384d5afc0116e0..0000000000000000000000000000000000000000 --- a/doc/doxygen/pkgdoc-howto.dox +++ /dev/null @@ -1,174 +0,0 @@ -/** - -\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 -één-op-éé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ërachische -\e view van zogenaamde \e modules op je project te creëeren. Hiervoor -zijn de commando's \c \\defgroup, \c \\ingroup en \c \\addtogroup beschikbaar. - - -\e Grouping is naar mijn idee éé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ë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ë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]" - -*/ diff --git a/doc/doxygen/quick-guide.cfg b/doc/doxygen/quick-guide.cfg deleted file mode 100644 index dc51fe2db6e7d7d007c00062086dc60da694aad9..0000000000000000000000000000000000000000 --- a/doc/doxygen/quick-guide.cfg +++ /dev/null @@ -1,4 +0,0 @@ -OUTPUT_DIRECTORY = . -INPUT = quick-guide.dox -EXAMPLE_PATH = examples -GENERATE_LATEX = NO diff --git a/doc/doxygen/quick-guide.cfg.in b/doc/doxygen/quick-guide.cfg.in new file mode 100644 index 0000000000000000000000000000000000000000..4a3f3668842a440b6f01e68f8614ac9e891cbcb0 --- /dev/null +++ b/doc/doxygen/quick-guide.cfg.in @@ -0,0 +1,5 @@ +HTML_OUTPUT = "@DOXYGEN_HTML_OUTPUT@/doxygen" +INPUT = quick-guide.dox +EXAMPLE_PATH = examples +GENERATE_LATEX = NO +GENERATE_TAGFILE = "@DOXYGEN_HTML_OUTPUT@/quick-guide.tag"