From 0c155cd6ed8ce25c5b5e4652b71a65bf4d0a5bb8 Mon Sep 17 00:00:00 2001 From: Wolfgang Bangerth Date: Wed, 6 Jan 2016 11:07:12 -0600 Subject: [PATCH] Build and track a page that lists all code gallery programs. --- doc/doxygen/CMakeLists.txt | 9 +++- doc/doxygen/code-gallery/CMakeLists.txt | 26 +++++++++- doc/doxygen/code-gallery/code-gallery.h.in | 40 ++++++++++++++++ doc/doxygen/scripts/code-gallery.pl | 56 ++++++++++++++++++++++ doc/doxygen/scripts/make_gallery.pl | 3 +- doc/doxygen/tutorial/tutorial.h.in | 13 +++-- 6 files changed, 140 insertions(+), 7 deletions(-) create mode 100644 doc/doxygen/code-gallery/code-gallery.h.in create mode 100644 doc/doxygen/scripts/code-gallery.pl diff --git a/doc/doxygen/CMakeLists.txt b/doc/doxygen/CMakeLists.txt index 490454dcaf..8814c586e8 100644 --- a/doc/doxygen/CMakeLists.txt +++ b/doc/doxygen/CMakeLists.txt @@ -1,6 +1,6 @@ ## --------------------------------------------------------------------- ## -## Copyright (C) 2012 - 2015 by the deal.II authors +## Copyright (C) 2012 - 2016 by the deal.II authors ## ## This file is part of the deal.II library. ## @@ -155,7 +155,14 @@ IF (EXISTS ${DEAL_II_CODE_GALLERY_DIRECTORY}/README.md) LIST(APPEND _doxygen_input ${CMAKE_CURRENT_BINARY_DIR}/code-gallery/${_step}.h ) + LIST(APPEND _doxygen_input + ${CMAKE_CURRENT_BINARY_DIR}/code-gallery/code-gallery.h + ) ENDFOREACH() + + LIST(APPEND _doxygen_depend + ${CMAKE_CURRENT_BINARY_DIR}/code-gallery/code-gallery.h + ) ENDIF() TO_STRING(_doxygen_image_path_string ${_doxygen_image_path}) diff --git a/doc/doxygen/code-gallery/CMakeLists.txt b/doc/doxygen/code-gallery/CMakeLists.txt index 8da41c5712..e98cae16c3 100644 --- a/doc/doxygen/code-gallery/CMakeLists.txt +++ b/doc/doxygen/code-gallery/CMakeLists.txt @@ -44,8 +44,32 @@ IF (EXISTS ${DEAL_II_CODE_GALLERY_DIRECTORY}/README.md) "${DEAL_II_CODE_GALLERY_DIRECTORY}/*/doc/author") STRING(REGEX REPLACE "/+doc/+author" "" _code_gallery_names "${_code_gallery_names}") - # Now set up targets for each of the code gallery programs + FOREACH(_step ${_code_gallery_names}) + GET_FILENAME_COMPONENT(_step "${_step}" NAME) + LIST(APPEND _code_gallery_names_sans_dir "${_step}") + ENDFOREACH() + # Describe how to build code-gallery.h: + ADD_CUSTOM_COMMAND( + OUTPUT ${CMAKE_CURRENT_BINARY_DIR}/code-gallery.h + COMMAND ${PERL_EXECUTABLE} + ARGS + ${CMAKE_SOURCE_DIR}/doc/doxygen/scripts/code-gallery.pl + ${CMAKE_CURRENT_SOURCE_DIR}/code-gallery.h.in + ${DEAL_II_CODE_GALLERY_DIRECTORY} + ${_code_gallery_names_sans_dir} + > ${CMAKE_CURRENT_BINARY_DIR}/code-gallery.h + DEPENDS + ${CMAKE_SOURCE_DIR}/doc/doxygen/scripts/code-gallery.pl + ${CMAKE_CURRENT_SOURCE_DIR}/code-gallery.h.in + ${_code_gallery_names} + ) + ADD_CUSTOM_TARGET(build_code-gallery_h + DEPENDS ${CMAKE_CURRENT_BINARY_DIR}/code-gallery.h) + ADD_DEPENDENCIES(code-gallery build_code-gallery_h) + + + # Now set up targets for each of the code gallery programs FOREACH(_step ${_code_gallery_names}) GET_FILENAME_COMPONENT(_step "${_step}" NAME) MESSAGE(STATUS " Setting up ${_step}") diff --git a/doc/doxygen/code-gallery/code-gallery.h.in b/doc/doxygen/code-gallery/code-gallery.h.in new file mode 100644 index 0000000000..207b15b11f --- /dev/null +++ b/doc/doxygen/code-gallery/code-gallery.h.in @@ -0,0 +1,40 @@ +// --------------------------------------------------------------------- +// +// Copyright (C) 2016 by the deal.II authors +// +// This file is part of the deal.II library. +// +// The deal.II library is free software; you can use it, redistribute +// it, and/or modify it under the terms of the GNU Lesser General +// Public License as published by the Free Software Foundation; either +// version 2.1 of the License, or (at your option) any later version. +// The full text of the license can be found in the file LICENSE at +// the top level of the deal.II distribution. +// +// --------------------------------------------------------------------- + + +/** + * @page CodeGallery The deal.II code gallery + * + * The deal.II code gallery contains a collection of programs based on deal.II + * that were contributed by others to serve as starting points for more complex + * applications. The code gallery is an extension of the @ref Tutorial "tutorial" + * in that the programs are intended to show how applications can be + * implemented with deal.II, but without the requirement to have these code + * documented at the same, extensive level as used in the tutorial. + * Instructions for obtaining the code gallery programs can be found at + * http://dealii.org/code-gallery.html . + * + * @note The programs that form part of the code gallery are contributed by + * others and are not part of deal.II itself. The deal.II authors make + * no assurances that these programs are documented in any reasonable way, + * nor that the programs are in fact correct. Please contact the authors + * of the code gallery programs if you have questions. + * + * The code gallery currently consists of the following programs (with + * connections to other programs shown in the graph on the + * @ref TutorialConnectionGraph "tutorial page"): + * +@@GALLERY_LIST@@ + */ diff --git a/doc/doxygen/scripts/code-gallery.pl b/doc/doxygen/scripts/code-gallery.pl new file mode 100644 index 0000000000..0bc718c33c --- /dev/null +++ b/doc/doxygen/scripts/code-gallery.pl @@ -0,0 +1,56 @@ +## --------------------------------------------------------------------- +## +## Copyright (C) 2016 by the deal.II authors +## +## This file is part of the deal.II library. +## +## The deal.II library is free software; you can use it, redistribute +## it, and/or modify it under the terms of the GNU Lesser General +## Public License as published by the Free Software Foundation; either +## version 2.1 of the License, or (at your option) any later version. +## The full text of the license can be found in the file LICENSE at +## the top level of the deal.II distribution. +## +## --------------------------------------------------------------------- + +use strict; + +my $gallery_file = shift; +open GALLERY, "<$gallery_file"; + +my $gallery_dir = shift; + + +# Print the first part of gallery.h.in up until the point where we +# find the line with '@@GALLERY_LIST@@' +while (my $line = ) +{ + last if($line =~ m/\@\@GALLERY_LIST\@\@/); + print $line; +} + +# print the list of code gallery programs as a descriptor/description +# list +print "
\n"; +foreach my $gallery (sort @ARGV) +{ + my $gallery_underscore = $gallery; + $gallery_underscore =~ s/-/_/; + print "
\@ref code_gallery_${gallery_underscore} \"$gallery\"
\n"; + print "
\n"; + open TOOLTIP, "<$gallery_dir/$gallery/doc/tooltip"; + while (my $line = ) { + print " $line"; + } + print "
\n"; + print "\n"; +} +print "
\n"; + + +# Then print the rest of code-gallery.h.in +while (my $line = ) +{ + print $line; +} +close GALLERY; diff --git a/doc/doxygen/scripts/make_gallery.pl b/doc/doxygen/scripts/make_gallery.pl index 245bff9025..06a2ebf88c 100644 --- a/doc/doxygen/scripts/make_gallery.pl +++ b/doc/doxygen/scripts/make_gallery.pl @@ -56,7 +56,8 @@ print \@endhtmlonly -This program consists of the following files (click to inspect): +This program is part of the \@ref CodeGallery \"deal.II code gallery\" and +consists of the following files (click to inspect): "; foreach my $file (@src_files) diff --git a/doc/doxygen/tutorial/tutorial.h.in b/doc/doxygen/tutorial/tutorial.h.in index ad8af33fc3..e072441e06 100644 --- a/doc/doxygen/tutorial/tutorial.h.in +++ b/doc/doxygen/tutorial/tutorial.h.in @@ -1,6 +1,6 @@ // --------------------------------------------------------------------- // -// Copyright (C) 2005 - 2015 by the deal.II authors +// Copyright (C) 2005 - 2016 by the deal.II authors // // This file is part of the deal.II library. // @@ -43,9 +43,6 @@ * synopsis of each program. *
  • or grouped by topic. * - * Some of the programs also jointly form - * the geodynamics - * demonstration suite. * * The programs are in the examples/ directory of your local * deal.II installation. After compiling the library itself, if you go into @@ -56,7 +53,15 @@ * different directories are based on the * small program Makefile template. * + * @note Some of the tutorial programs also jointly form + * the geodynamics + * demonstration suite. More, often more complex but less well documented, + * deal.II-based programs than the ones that form the tutorial can also be + * found in the @ref CodeGallery . + * + * * + * @anchor TutorialConnectionGraph *

    Connections between tutorial programs

    * * The following graph shows the connections between tutorial programs and -- 2.39.5