From 6a5612761bbdff121d1dd27111a95f3a32421fa9 Mon Sep 17 00:00:00 2001
From: Michael Wild
Date: Wed, 3 Jun 2009 18:31:02 +0200
Subject: [PATCH] ENH: More flexible -doc and -srcDoc options using index file
argList.C now doesn't search docDirs directly, but uses an index file
for this. This allows also www paths to be referenced. Further, multiple
documentation index files can be specified, each with its own directory
prefix. The "master" documentation index file is created by CMake using
the new FF_ADD_EXECUTABLE_TO_DOC_INDEX function.
The user can now choose to use the online or the local docs
(FF_USE_LOCAL_DOXYGE_DOCS) and if she doesn't want to use a
HTML browser, she can set HTML_DOC_BROWSER to "ECHO" which will cause
FreeFOAM to just output the name and location of the documentation file.
Signed-off-by: Michael Wild
---
CMake/Modules/FFAddExecutableToDocIndex.cmake | 137 +++++++++++++++++++++
CMake/Modules/FFConfigureFiles.cmake | 16 ++-
CMakeLists.txt | 23 +++-
INSTALL | 22 ++++
INSTALL.html | 42 ++++++-
applications/solvers/DNS/dnsFoam/CMakeLists.txt | 2 +
.../solvers/basic/laplacianFoam/CMakeLists.txt | 2 +
.../solvers/basic/potentialFoam/CMakeLists.txt | 2 +
.../basic/scalarTransportFoam/CMakeLists.txt | 2 +
.../solvers/combustion/PDRFoam/CMakeLists.txt | 2 +
.../solvers/combustion/XiFoam/CMakeLists.txt | 2 +
.../solvers/combustion/Xoodles/CMakeLists.txt | 2 +
.../combustion/coldEngineFoam/CMakeLists.txt | 2 +
.../combustion/dieselEngineFoam/CMakeLists.txt | 2 +
.../solvers/combustion/dieselFoam/CMakeLists.txt | 2 +
.../solvers/combustion/engineFoam/CMakeLists.txt | 2 +
.../solvers/combustion/reactingFoam/CMakeLists.txt | 2 +
.../solvers/compressible/coodles/CMakeLists.txt | 2 +
.../compressible/rhoCentralFoam/CMakeLists.txt | 2 +
.../compressible/rhoPimpleFoam/CMakeLists.txt | 2 +
.../rhoPorousSimpleFoam/CMakeLists.txt | 2 +
.../compressible/rhoSimpleFoam/CMakeLists.txt | 2 +
.../compressible/rhoSonicFoam/CMakeLists.txt | 2 +
.../compressible/rhoTurbFoam/CMakeLists.txt | 2 +
.../compressible/rhopSonicFoam/CMakeLists.txt | 2 +
.../solvers/compressible/sonicFoam/CMakeLists.txt | 2 +
.../sonicFoamAutoMotion/CMakeLists.txt | 2 +
.../compressible/sonicLiquidFoam/CMakeLists.txt | 2 +
.../compressible/sonicTurbFoam/CMakeLists.txt | 2 +
.../electrostaticFoam/CMakeLists.txt | 2 +
.../electromagnetics/mhdFoam/CMakeLists.txt | 2 +
.../solvers/financial/financialFoam/CMakeLists.txt | 2 +
.../heatTransfer/buoyantFoam/CMakeLists.txt | 2 +
.../heatTransfer/buoyantSimpleFoam/CMakeLists.txt | 2 +
.../buoyantSimpleRadiationFoam/CMakeLists.txt | 2 +
.../heatTransfer/chtMultiRegionFoam/CMakeLists.txt | 2 +
.../heatTransfer/lesBuoyantFoam/CMakeLists.txt | 2 +
.../incompressible/boundaryFoam/CMakeLists.txt | 2 +
.../incompressible/channelOodles/CMakeLists.txt | 2 +
.../incompressible/icoDyMFoam/CMakeLists.txt | 2 +
.../solvers/incompressible/icoFoam/CMakeLists.txt | 2 +
.../nonNewtonianIcoFoam/CMakeLists.txt | 2 +
.../solvers/incompressible/oodles/CMakeLists.txt | 2 +
.../incompressible/simpleFoam/CMakeLists.txt | 2 +
.../incompressible/turbDyMFoam/CMakeLists.txt | 2 +
.../solvers/incompressible/turbFoam/CMakeLists.txt | 2 +
.../molecularDynamics/gnemdFoam/CMakeLists.txt | 2 +
.../mdEquilibrationFoam/CMakeLists.txt | 2 +
.../solvers/multiphase/bubbleFoam/CMakeLists.txt | 2 +
.../compressibleLesInterFoam/CMakeLists.txt | 2 +
.../solvers/multiphase/interDyMFoam/CMakeLists.txt | 2 +
.../solvers/multiphase/interFoam/CMakeLists.txt | 2 +
.../multiphase/interPhaseChangeFoam/CMakeLists.txt | 2 +
.../multiphase/lesCavitatingFoam/CMakeLists.txt | 2 +
.../solvers/multiphase/lesInterFoam/CMakeLists.txt | 2 +
.../multiphase/multiphaseInterFoam/CMakeLists.txt | 2 +
.../multiphase/rasCavitatingFoam/CMakeLists.txt | 2 +
.../solvers/multiphase/rasInterFoam/CMakeLists.txt | 2 +
.../solvers/multiphase/settlingFoam/CMakeLists.txt | 2 +
.../multiphase/twoLiquidMixingFoam/CMakeLists.txt | 2 +
.../multiphase/twoPhaseEulerFoam/CMakeLists.txt | 2 +
.../solidDisplacementFoam/CMakeLists.txt | 2 +
.../CMakeLists.txt | 2 +
.../estimateScalarError/CMakeLists.txt | 2 +
.../icoErrorEstimate/CMakeLists.txt | 2 +
.../errorEstimation/icoMomentError/CMakeLists.txt | 2 +
.../momentScalarError/CMakeLists.txt | 2 +
.../mesh/advanced/autoRefineMesh/CMakeLists.txt | 2 +
.../mesh/advanced/collapseEdges/CMakeLists.txt | 2 +
.../mesh/advanced/combinePatchFaces/CMakeLists.txt | 2 +
.../mesh/advanced/modifyMesh/CMakeLists.txt | 2 +
.../mesh/advanced/refineHexMesh/CMakeLists.txt | 2 +
.../mesh/advanced/refineWallLayer/CMakeLists.txt | 2 +
.../mesh/advanced/refinementLevel/CMakeLists.txt | 2 +
.../mesh/advanced/removeFaces/CMakeLists.txt | 2 +
.../mesh/advanced/selectCells/CMakeLists.txt | 2 +
.../mesh/advanced/splitCells/CMakeLists.txt | 2 +
.../conversion/Optional/ccm26ToFoam/CMakeLists.txt | 2 +
.../mesh/conversion/ansysToFoam/CMakeLists.txt | 2 +
.../mesh/conversion/cfx4ToFoam/CMakeLists.txt | 2 +
.../conversion/fluent3DMeshToFoam/CMakeLists.txt | 2 +
.../conversion/fluentMeshToFoam/CMakeLists.txt | 2 +
.../conversion/foamMeshToFluent/CMakeLists.txt | 2 +
.../mesh/conversion/foamToStarMesh/CMakeLists.txt | 2 +
.../mesh/conversion/gambitToFoam/CMakeLists.txt | 2 +
.../mesh/conversion/gmshToFoam/CMakeLists.txt | 2 +
.../mesh/conversion/ideasUnvToFoam/CMakeLists.txt | 2 +
.../mesh/conversion/kivaToFoam/CMakeLists.txt | 2 +
.../mesh/conversion/mshToFoam/CMakeLists.txt | 2 +
.../conversion/netgenNeutralToFoam/CMakeLists.txt | 2 +
.../mesh/conversion/plot3dToFoam/CMakeLists.txt | 2 +
.../mesh/conversion/polyDualMesh/CMakeLists.txt | 2 +
.../mesh/conversion/sammToFoam/CMakeLists.txt | 2 +
.../mesh/conversion/star4ToFoam/CMakeLists.txt | 2 +
.../mesh/conversion/starToFoam/CMakeLists.txt | 2 +
.../mesh/conversion/tetgenToFoam/CMakeLists.txt | 2 +
.../mesh/conversion/writeMeshObj/CMakeLists.txt | 2 +
.../mesh/generation/blockMesh/CMakeLists.txt | 2 +
.../mesh/generation/extrude2DMesh/CMakeLists.txt | 2 +
.../mesh/generation/extrudeMesh/CMakeLists.txt | 2 +
.../mesh/generation/snappyHexMesh/CMakeLists.txt | 2 +
.../mesh/manipulation/attachMesh/CMakeLists.txt | 2 +
.../mesh/manipulation/autoPatch/CMakeLists.txt | 2 +
.../mesh/manipulation/cellSet/CMakeLists.txt | 2 +
.../manipulation/checkMesh.save/CMakeLists.txt | 2 +
.../mesh/manipulation/checkMesh/CMakeLists.txt | 2 +
.../mesh/manipulation/createBaffles/CMakeLists.txt | 2 +
.../mesh/manipulation/createPatch/CMakeLists.txt | 2 +
.../mesh/manipulation/deformedGeom/CMakeLists.txt | 2 +
.../mesh/manipulation/faceSet/CMakeLists.txt | 2 +
.../mesh/manipulation/flattenMesh/CMakeLists.txt | 2 +
.../mesh/manipulation/insideCells/CMakeLists.txt | 2 +
.../mesh/manipulation/mergeMeshes/CMakeLists.txt | 2 +
.../mergeOrSplitBaffles/CMakeLists.txt | 2 +
.../mesh/manipulation/mirrorMesh/CMakeLists.txt | 2 +
.../manipulation/moveDynamicMesh/CMakeLists.txt | 2 +
.../manipulation/moveEngineMesh/CMakeLists.txt | 2 +
.../mesh/manipulation/moveMesh/CMakeLists.txt | 2 +
.../mesh/manipulation/objToVTK/CMakeLists.txt | 2 +
.../mesh/manipulation/pointSet/CMakeLists.txt | 2 +
.../mesh/manipulation/refineMesh/CMakeLists.txt | 2 +
.../mesh/manipulation/renumberMesh/CMakeLists.txt | 2 +
.../mesh/manipulation/rotateMesh/CMakeLists.txt | 2 +
.../mesh/manipulation/setSet/CMakeLists.txt | 2 +
.../mesh/manipulation/setsToZones/CMakeLists.txt | 2 +
.../mesh/manipulation/splitMesh/CMakeLists.txt | 2 +
.../manipulation/splitMeshRegions/CMakeLists.txt | 2 +
.../mesh/manipulation/stitchMesh/CMakeLists.txt | 2 +
.../mesh/manipulation/subsetMesh/CMakeLists.txt | 2 +
.../manipulation/transformPoints/CMakeLists.txt | 2 +
.../mesh/manipulation/zipUpMesh/CMakeLists.txt | 2 +
.../miscellaneous/expandDictionary/CMakeLists.txt | 2 +
.../miscellaneous/foamDebugSwitches/CMakeLists.txt | 2 +
.../miscellaneous/foamFormatConvert/CMakeLists.txt | 2 +
.../miscellaneous/foamInfoExec/CMakeLists.txt | 2 +
.../miscellaneous/patchSummary/CMakeLists.txt | 2 +
.../parallelProcessing/decomposePar/CMakeLists.txt | 2 +
.../reconstructPar/CMakeLists.txt | 2 +
.../reconstructParMesh/CMakeLists.txt | 2 +
.../redistributeMeshPar/CMakeLists.txt | 2 +
.../dataConversion/foamDataToFluent/CMakeLists.txt | 2 +
.../dataConversion/foamToEnsight/CMakeLists.txt | 2 +
.../foamToEnsightParts/CMakeLists.txt | 2 +
.../dataConversion/foamToFieldview9/CMakeLists.txt | 2 +
.../dataConversion/foamToGMV/CMakeLists.txt | 2 +
.../dataConversion/foamToVTK/CMakeLists.txt | 2 +
.../dataConversion/smapToFoam/CMakeLists.txt | 2 +
.../postProcessing/foamCalc/CMakeLists.txt | 2 +
.../miscellaneous/engineCompRatio/CMakeLists.txt | 2 +
.../execFlowFunctionObjects/CMakeLists.txt | 2 +
.../miscellaneous/pdfPlot/CMakeLists.txt | 2 +
.../miscellaneous/postChannel/CMakeLists.txt | 2 +
.../miscellaneous/ptot/CMakeLists.txt | 2 +
.../miscellaneous/wdot/CMakeLists.txt | 2 +
.../miscellaneous/writeCellCentres/CMakeLists.txt | 2 +
.../patch/patchAverage/CMakeLists.txt | 2 +
.../patch/patchIntegrate/CMakeLists.txt | 2 +
.../sampling/probeLocations/CMakeLists.txt | 2 +
.../postProcessing/sampling/sample/CMakeLists.txt | 2 +
.../scalarField/pPrime2/CMakeLists.txt | 2 +
.../stressField/stressComponents/CMakeLists.txt | 2 +
.../postProcessing/turbulence/R/CMakeLists.txt | 2 +
.../createTurbulenceFields/CMakeLists.txt | 2 +
.../postProcessing/velocityField/Co/CMakeLists.txt | 2 +
.../velocityField/Lambda2/CMakeLists.txt | 2 +
.../velocityField/Mach/CMakeLists.txt | 2 +
.../postProcessing/velocityField/Pe/CMakeLists.txt | 2 +
.../postProcessing/velocityField/Q/CMakeLists.txt | 2 +
.../velocityField/enstrophy/CMakeLists.txt | 2 +
.../velocityField/flowType/CMakeLists.txt | 2 +
.../velocityField/streamFunction/CMakeLists.txt | 2 +
.../velocityField/uprime/CMakeLists.txt | 2 +
.../velocityField/vorticity/CMakeLists.txt | 2 +
.../postProcessing/wall/wallGradU/CMakeLists.txt | 2 +
.../wall/wallHeatFlux/CMakeLists.txt | 2 +
.../wall/wallShearStress/CMakeLists.txt | 2 +
.../postProcessing/wall/yPlusLES/CMakeLists.txt | 2 +
.../postProcessing/wall/yPlusRAS/CMakeLists.txt | 2 +
.../applyBoundaryLayer/CMakeLists.txt | 2 +
.../utilities/preProcessing/boxTurb/CMakeLists.txt | 2 +
.../preProcessing/changeDictionary/CMakeLists.txt | 2 +
.../preProcessing/engineSwirl/CMakeLists.txt | 2 +
.../preProcessing/mapFields/CMakeLists.txt | 2 +
.../preProcessing/molConfig/CMakeLists.txt | 2 +
.../preProcessing/setFields/CMakeLists.txt | 2 +
.../utilities/surface/surfaceAdd/CMakeLists.txt | 2 +
.../surface/surfaceAutoPatch/CMakeLists.txt | 2 +
.../utilities/surface/surfaceCheck/CMakeLists.txt | 2 +
.../utilities/surface/surfaceClean/CMakeLists.txt | 2 +
.../surface/surfaceCoarsen/CMakeLists.txt | 2 +
.../surface/surfaceConvert/CMakeLists.txt | 2 +
.../surface/surfaceFeatureConvert/CMakeLists.txt | 2 +
.../surface/surfaceFeatureExtract/CMakeLists.txt | 2 +
.../utilities/surface/surfaceFind/CMakeLists.txt | 2 +
.../surface/surfaceMeshTriangulate/CMakeLists.txt | 2 +
.../utilities/surface/surfaceOrient/CMakeLists.txt | 2 +
.../surface/surfacePointMerge/CMakeLists.txt | 2 +
.../surface/surfaceRefineRedGreen/CMakeLists.txt | 2 +
.../utilities/surface/surfaceSmooth/CMakeLists.txt | 2 +
.../surface/surfaceSplitByPatch/CMakeLists.txt | 2 +
.../surfaceSplitNonManifolds/CMakeLists.txt | 2 +
.../utilities/surface/surfaceSubset/CMakeLists.txt | 2 +
.../surface/surfaceToPatch/CMakeLists.txt | 2 +
.../surface/surfaceTransformPoints/CMakeLists.txt | 2 +
.../thermophysical/adiabaticFlameT/CMakeLists.txt | 2 +
.../thermophysical/chemkinToFoam/CMakeLists.txt | 2 +
.../thermophysical/equilibriumCO/CMakeLists.txt | 2 +
.../equilibriumFlameT/CMakeLists.txt | 2 +
.../mixtureAdiabaticFlameT/CMakeLists.txt | 2 +
etc/controlDict.in | 6 +-
src/OpenFOAM/global/argList/argList.C | 70 +++++++++--
src/OpenFOAM/global/foamVersion.H | 1 +
src/OpenFOAM/global/global.C.in | 1 +
213 files changed, 710 insertions(+), 16 deletions(-)
create mode 100644 CMake/Modules/FFAddExecutableToDocIndex.cmake
diff --git a/CMake/Modules/FFAddExecutableToDocIndex.cmake b/CMake/Modules/FFAddExecutableToDocIndex.cmake
new file mode 100644
index 000000000..e4b28d794
--- /dev/null
+++ b/CMake/Modules/FFAddExecutableToDocIndex.cmake
@@ -0,0 +1,137 @@
+#-------------------------------------------------------------------------------
+# ______ _ ____ __ __
+# | ____| _| |_ / __ \ /\ | \/ |
+# | |__ _ __ ___ ___ / \| | | | / \ | \ / |
+# | __| '__/ _ \/ _ ( (| |) ) | | |/ /\ \ | |\/| |
+# | | | | | __/ __/\_ _/| |__| / ____ \| | | |
+# |_| |_| \___|\___| |_| \____/_/ \_\_| |_|
+#
+# FreeFOAM: The Cross-Platform CFD Toolkit
+#
+# Copyright (C) 2008-2009 Michael Wild
+# Gerber van der Graaf
+#-------------------------------------------------------------------------------
+# License
+# This file is part of FreeFOAM.
+#
+# FreeFOAM is free software; you can redistribute it and/or modify it
+# under the terms of the GNU General Public License as published by the
+# Free Software Foundation; either version 2 of the License, or (at your
+# option) any later version.
+#
+# FreeFOAM is distributed in the hope that it will be useful, but WITHOUT
+# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+# FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
+# for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with FreeFOAM; if not, write to the Free Software Foundation,
+# Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA
+#-------------------------------------------------------------------------------
+
+# - Create a documentation index file
+#
+# CAUTION: Include this file only once!
+#
+# To add an exeutable to the index, use:
+# FF_ADD_EXECUTABLE_TO_DOC_INDEX( TARGET1 [TARGET2...] )
+#
+# TARGET1... The executable targets to add to the doc index
+#
+# DO NOT call this function after you called
+# FF_WRITE_DOC_INDEX, it won't have any effect!
+#
+# At the very end of your "master"-CMakeLists file, call:
+# FF_WRITE_DOC_INDEX()
+# This will create
+# ${CMAKE_BINARY_DIR}/data/DoxyDocIndex.in
+# ${CMAKE_BINARY_DIR}/data/DoxyDocIndex
+# ${CMAKE_BINARY_DIR}/InstallFiles/data/DoxyDocIndex
+
+# remove the list of documented apps from the cache
+#TODO use UNSET once it is available in mainstream distros
+set( __FF_ADD_EXECUTABLE_TO_DOC_INDEX_targets
+ CACHE INTERNAL "PURGED" FORCE
+ )
+
+function( FF_ADD_EXECUTABLE_TO_DOC_INDEX )
+ set( files )
+ foreach( f ${ARGN} )
+ list( APPEND files "${f}_8C.html" "${f}_8C-source.html" )
+ endforeach( f )
+ set( __FF_ADD_EXECUTABLE_TO_DOC_INDEX_targets
+ ${__FF_ADD_EXECUTABLE_TO_DOC_INDEX_targets} ${files}
+ CACHE INTERNAL "Files to include in the documentation index"
+ FORCE
+ )
+endfunction( FF_ADD_EXECUTABLE_TO_DOC_INDEX )
+
+include( FFConfigureFiles )
+
+function( FF_WRITE_DOC_INDEX )
+ # construct the list of files
+ string( REPLACE ";" "\"\n \"" tmp " \"${__FF_ADD_EXECUTABLE_TO_DOC_INDEX_targets}\"" )
+ # get the version string right
+ string( LENGTH ${FF_VERSION_FULL} verlength )
+ set( verstr " " )
+ math( EXPR verspacelength "48-${verlength}" )
+ string( SUBSTRING "${verstr}" 0 ${verspacelength} verstr )
+ set( verstr "${FF_VERSION_FULL}${verstr}" )
+ # write the doc index file
+ file( WRITE ${CMAKE_BINARY_DIR}/data/DoxyDocIndex.in
+"/*--------------------------------*- C++ -*----------------------------------*\\
+| ______ _ ____ __ __ |
+| | ____| _| |_ / __ \\ /\\ | \\/ | |
+| | |__ _ __ ___ ___ / \\| | | | / \\ | \\ / | |
+| | __| '__/ _ \\/ _ ( (| |) ) | | |/ /\\ \\ | |\\/| | |
+| | | | | | __/ __/\\_ _/| |__| / ____ \\| | | | |
+| |_| |_| \\___|\\___| |_| \\____/_/ \\_\\_| |_| |
+| |
+| FreeFOAM: The Cross-Platform CFD Toolkit |
+| Version: ${verstr}|
+| Web: http://freefoam.sourceforge.net |
+\\*---------------------------------------------------------------------------*/
+FoamFile
+{
+version 2.0;
+format ascii;
+class dictionary;
+object docIndex;
+}
+// * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * //
+
+docDir \"@FF_DOC_DIR@/Doxygen/html\";
+
+docFiles (
+${tmp}
+);
+
+// ********************* vim: set ft=cpp sw=4 sts=4 et: ******************** //
+"
+ )
+
+ # annoying duplication of ff_configure_files, but that one can't be used
+ # because it would put things in
+ # ${CMAKE_BINARY_DIR}/data/${CMAKE_BINARY_DIR}/DoxyDocIndex and
+ # ${CMAKE_BINARY_DIR}/InstallFiles/data/${CMAKE_BINARY_DIR}/DoxyDocIndex.
+
+ # binary tree
+ set( FF_DOC_DIR "http://freefoam.sf.net/doc" )
+ set( FF_LOCAL_DOC_DIR ${CMAKE_BINARY_DIR}/doc )
+ if( FF_USE_LOCAL_DOXYGEN_DOCS )
+ set( FF_DOC_DIR ${FF_LOCAL_DOC_DIR} )
+ endif( FF_USE_LOCAL_DOXYGEN_DOCS )
+ configure_file( ${CMAKE_BINARY_DIR}/data/DoxyDocIndex.in
+ ${CMAKE_BINARY_DIR}/data/DoxyDocIndex @ONLY )
+
+ # install tree
+ set( FF_LOCAL_DOC_DIR ${FF_INSTALL_DOC_PATH} )
+ if( FF_USE_LOCAL_DOXYGEN_DOCS )
+ set( FF_DOC_DIR ${FF_LOCAL_DOC_DIR} )
+ endif( FF_USE_LOCAL_DOXYGEN_DOCS )
+ configure_file( ${CMAKE_BINARY_DIR}/data/DoxyDocIndex.in
+ ${CMAKE_BINARY_DIR}/InstallFiles/data/DoxyDocIndex @ONLY )
+
+endfunction( FF_WRITE_DOC_INDEX )
+
+# ------------------------- vim: set ft=cmake sw=2 sts=2 et: --------------- end-of-file
diff --git a/CMake/Modules/FFConfigureFiles.cmake b/CMake/Modules/FFConfigureFiles.cmake
index 9e82023c3..bfdb29dd7 100644
--- a/CMake/Modules/FFConfigureFiles.cmake
+++ b/CMake/Modules/FFConfigureFiles.cmake
@@ -60,9 +60,12 @@
# - FF_DATA_DIR:
# - build tree: ${CMAKE_BINARY_DIR}/data
# - install tree: ${FF_INSTALL_DATA_PATH}
-# - FF_DOC_DIR:
+# - FF_LOCAL_DOC_DIR:
# - build tree: ${CMAKE_BINARY_DIR}/doc
# - install tree: ${FF_INSTALL_DOC_PATH}
+# - FF_DOC_DIR:
+# If FF_USE_LOCAL_DOXYGEN_DOCS is TRUE this equals to FF_LOCAL_DOC_DIR,
+# else it is set to http://freefoam.sf.net/doc
# - FF_BIN_DIR:
# - build tree: ${CMAKE_BINARY_DIR}/bin
# - install tree: ${FF_INSTALL_BIN_PATH}
@@ -88,6 +91,7 @@ macro( FF_CONFIGURE_FILES _buildFilesVar _installFilesVar _destDir )
set( ${_buildFilesVar} )
#TODO use UNSET once it is available in mainstream distros
set( ${_installFilesVar} )
+ set( FF_DOC_DIR "http://freefoam.sf.net/doc" )
# loop over files
foreach( _s ${ARGN} )
if( _s STREQUAL FILEPREFIX )
@@ -111,7 +115,10 @@ macro( FF_CONFIGURE_FILES _buildFilesVar _installFilesVar _destDir )
set( FF_BIN_DIR ${CMAKE_BINARY_DIR}/bin )
set( FF_LIB_DIR ${FF_LIBRARY_OUTPUT_DIRECTORY} )
set( FF_DATA_DIR ${CMAKE_BINARY_DIR}/data )
- set( FF_DOC_DIR ${CMAKE_BINARY_DIR}/doc )
+ set( FF_LOCAL_DOC_DIR ${CMAKE_BINARY_DIR}/doc )
+ if( FF_USE_LOCAL_DOXYGEN_DOCS )
+ set( FF_DOC_DIR ${FF_LOCAL_DOC_DIR} )
+ endif( FF_USE_LOCAL_DOXYGEN_DOCS )
set( FF_CONFIG_DIR ${CMAKE_BINARY_DIR}/etc )
set( FF_CMAKECONFIG_DIR ${CMAKE_BINARY_DIR} )
set( FF_IS_INSTALLED FALSE )
@@ -122,7 +129,10 @@ macro( FF_CONFIGURE_FILES _buildFilesVar _installFilesVar _destDir )
set( FF_BIN_DIR ${FF_INSTALL_BIN_PATH} )
set( FF_LIB_DIR ${FF_INSTALL_LIB_PATH} )
set( FF_DATA_DIR ${FF_INSTALL_DATA_PATH} )
- set( FF_DOC_DIR ${FF_INSTALL_DOC_PATH} )
+ set( FF_LOCAL_DOC_DIR ${FF_INSTALL_DOC_PATH} )
+ if( FF_USE_LOCAL_DOXYGEN_DOCS )
+ set( FF_DOC_DIR ${FF_LOCAL_DOC_DIR} )
+ endif( FF_USE_LOCAL_DOXYGEN_DOCS )
set( FF_CONFIG_DIR ${FF_INSTALL_CONFIG_PATH} )
set( FF_CMAKECONFIG_DIR ${FF_INSTALL_LIB_PATH} )
set( FF_IS_INSTALLED TRUE )
diff --git a/CMakeLists.txt b/CMakeLists.txt
index bae060e28..1bf4ea2d7 100644
--- a/CMakeLists.txt
+++ b/CMakeLists.txt
@@ -106,17 +106,20 @@ endif( APPLE AND FF_BUILD_FRAMEWORK )
# select html documentation browser (try a few well known ones for default)
# have to loop, because find_program( HTML_DOC_BROWSER NAMES ... ) garbles things up
-foreach( browser open kde-open gnome-open x-www-browser www-browser firefox epiphany konqueror w3m lynx open )
+foreach( browser open gnome-open kde-open x-www-browser www-browser
+ firefox epiphany konqueror w3m lynx launch open )
find_program( HTML_DOC_BROWSER ${browser}
DOC "Program to open an HTML file" )
if( HTML_DOC_BROWSER )
- set( FF_HTML_DOC_BROWSER_COMMAND "${HTML_DOC_BROWSER} %f" CACHE STRING "Command to open an HTML file" )
break()
endif( HTML_DOC_BROWSER )
endforeach( browser )
if( NOT HTML_DOC_BROWSER )
- message( SEND_ERROR "Failed to find a program to open HTML pages with (a.k.a a browser). Point HTML_DOC_BROWSER to a suitable program." )
+ message( STATUS "Failed to find a program to open HTML pages with (a.k.a a browser). Point HTML_DOC_BROWSER to a suitable program." )
+ set( HTML_DOC_BROWSER "ECHO" CACHE STRING "Command to open an HTML file (ECHO will print it to STDOUT)" FORCE )
endif( NOT HTML_DOC_BROWSER )
+set( FF_HTML_DOC_BROWSER_COMMAND "\${HTML_DOC_BROWSER} %f" CACHE STRING "Command to open an HTML file" )
+string( CONFIGURE "${FF_HTML_DOC_BROWSER_COMMAND}" FF_HTML_DOC_BROWSER_COMMAND ESCAPE_QUOTES )
mark_as_advanced( HTML_DOC_BROWSER FF_HTML_DOC_BROWSER_COMMAND )
# set up the RPATH for installation
@@ -171,6 +174,7 @@ endif( NOT ZLIB_FOUND )
include( FFConfigureFiles )
include( FFDetectChangedValue )
include( FFExportTargetsToBuildTree )
+include( FFAddExecutableToDocIndex )
include( FFLinkLoadableLibrary )
# find metis (recent distros have it in their repository, so default to search for that)
@@ -287,6 +291,11 @@ if( FF_ENABLE_DOXYGEN_DOCS )
endif( FF_ENABLE_DOXYGEN_DOCS )
mark_as_advanced( FF_ENABLE_DOXYGEN_DOCS )
+# ask user whether she prefers local or www docs
+option( FF_USE_LOCAL_DOXYGEN_DOCS
+ "Use the local Doxygen documentation instead of the one on http://freefoam.sf.net/doc/Doxygen/html" OFF )
+mark_as_advanced( FF_USE_LOCAL_DOXYGEN_DOCS )
+
# find m4 macro processor
find_program( M4_EXECUTABLE m4 DOC "Path to the m4 macro processor" )
mark_as_advanced( M4_EXECUTABLE )
@@ -348,6 +357,14 @@ add_subdirectory( tutorials )
# export the library dependencies to the build tree
ff_export_targets_to_build_tree()
+# write the doc index file and install it
+ff_write_doc_index()
+install( FILES
+ ${CMAKE_BINARY_DIR}/InstallFiles/data/DoxyDocIndex
+ DESTINATION ${FF_INSTALL_DATA_PATH}
+ COMPONENT data
+ )
+
# export build settings and library dependencies
include( CMakeExportBuildSettings )
cmake_export_build_settings( ${FF_LIBRARY_OUTPUT_DIRECTORY}/FreeFOAMBuildSettings.cmake )
diff --git a/INSTALL b/INSTALL
index 04790f320..3f0035b6a 100644
--- a/INSTALL
+++ b/INSTALL
@@ -380,6 +380,28 @@ actions.
depends on a huge number of files and would make dependency tracking very
slow and difficult to maintain. To force the re-generation of the API
documentation execute +make apidoc+.
++FF_USE_LOCAL_DOXYGEN_DOCS+::
+ This setting influences the location in which the Doxygen source
+ code documentation is looked for if any of the FreeFOAM applications
+ is invoked with the '-doc' or '-srcDoc' options. If it is disabled,
+ the documentation will be loaded over the network from
+ http://freefoam.sf.net/doc/Doxygen/html. If you enable it, the
+ documentation will be loaded locally. This requires that you either
+ build and install the documentation by enabling +FF_BUILD_DOXYGEN_DOCS+,
+ or provide the required HTML files otherwise.
++HTML_DOC_BROWSER+::
+ This is the program used to display the Doxygen source code documentation
+ if any of the FreeFOAM applications is invoked with the '-doc' or '-srcDoc'
+ options. The special value of 'ECHO' changes the behaviour to just write
+ the location of the HTML file to the output. This is a good setting if
+ you're system doesn't have any kind of HTML browser installed (such
+ as on a cluster).
++FF_HTML_DOC_BROWSER_COMMAND+::
+ This is the command with which to invoke the HTML browser. By default
+ it calls the program named in +HTML_DOC_BROWSER+ and passes it the
+ name/URL of the documentation file to be displayed. You shouldn't
+ have to change this unless your HTML browser requires some unusual
+ options or arguments.
Troubleshooting
---------------
diff --git a/INSTALL.html b/INSTALL.html
index 7f13d66b4..1a19c8b88 100644
--- a/INSTALL.html
+++ b/INSTALL.html
@@ -1173,6 +1173,46 @@ actions.
documentation execute make apidoc.
+
+FF_USE_LOCAL_DOXYGEN_DOCS
+
+
+
+ This setting influences the location in which the Doxygen source
+ code documentation is looked for if any of the FreeFOAM applications
+ is invoked with the -doc or -srcDoc options. If it is disabled,
+ the documentation will be loaded over the network from
+ http://freefoam.sf.net/doc/Doxygen/html. If you enable it, the
+ documentation will be loaded locally. This requires that you either
+ build and install the documentation by enabling FF_BUILD_DOXYGEN_DOCS,
+ or provide the required HTML files otherwise.
+
+
+
+HTML_DOC_BROWSER
+
+
+
+ This is the program used to display the Doxygen source code documentation
+ if any of the FreeFOAM applications is invoked with the -doc or -srcDoc
+ options. The special value of ECHO changes the behaviour to just write
+ the location of the HTML file to the output. This is a good setting if
+ you’re system doesn’t have any kind of HTML browser installed (such
+ as on a cluster).
+
+
+
+FF_HTML_DOC_BROWSER_COMMAND
+
+
+
+ This is the command with which to invoke the HTML browser. By default
+ it calls the program named in HTML_DOC_BROWSER and passes it the
+ name/URL of the documentation file to be displayed. You shouldn’t
+ have to change this unless your HTML browser requires some unusual
+ options or arguments.
+
+
7. Troubleshooting
@@ -1387,7 +1427,7 @@ variable to update the cache of available programs.