]> https://gitweb.dealii.org/ - dealii-svn.git/commitdiff
*Yay* Add support for building the doxygen documentation
authormaier <maier@0785d39b-7218-0410-832d-ea1e28bc413d>
Mon, 8 Oct 2012 23:30:09 +0000 (23:30 +0000)
committermaier <maier@0785d39b-7218-0410-832d-ea1e28bc413d>
Mon, 8 Oct 2012 23:30:09 +0000 (23:30 +0000)
git-svn-id: https://svn.dealii.org/branches/branch_cmake@27017 0785d39b-7218-0410-832d-ea1e28bc413d

12 files changed:
deal.II/TODO.CMAKE
deal.II/doc/CMakeLists.txt
deal.II/doc/doxygen/CMakeLists.txt
deal.II/doc/doxygen/options.dox.in
deal.II/doc/doxygen/tutorial/CMakeLists.txt
deal.II/doc/doxygen/tutorial/Makefile [deleted file]
deal.II/doc/doxygen/tutorial/_plain.snippet.in [new file with mode: 0644]
deal.II/doc/doxygen/tutorial/_toc.final.snippet [new file with mode: 0644]
deal.II/doc/doxygen/tutorial/_toc.intro.snippet.in [new file with mode: 0644]
deal.II/doc/doxygen/tutorial/_toc.prog.snippet [new file with mode: 0644]
deal.II/doc/doxygen/tutorial/_toc.results.snippet [new file with mode: 0644]
deal.II/doc/scripts/intro2toc

index 1c935cc0272dc013e40a9d1849701795ec35ea03..2773ec541015130078e38c3f30615ba2ca6953c2 100644 (file)
@@ -1,8 +1,5 @@
 Major:
 
-* Implement the documentation component. (I don't grok what's going on in
-  this makefiles. There is a rudimentary doxygen call, though.)
-
 * Add the rest of the Bug tests
 
 * Test the fparser 4.5 functionality.
@@ -13,7 +10,6 @@ Major:
     * TECPLOT
 
 * Write a wrapper around cmake. Something like
-    * download and 'install' cmake if necessary
     $ make config
     $ make
     ...
@@ -29,11 +25,11 @@ Major:
 * Rename all DEAL_II_USE_* and HAVE_LIB* that refer to a feature to
   DEAL_II_WITH_*.
 
-* Refactor lapack_templates.pl
-
 
 Minor:
 
+* (Maybe) re-enable validate-xrefs
+
 * Fixup the TODOs in
     source/lac/sparse_dircect.cc
     source/base/path_find.cc
index 3e846328b32a3596c8b20d3b98c8fbb91fecb505..c09c7dfeed603075df7414b0ca20de28b0349f15 100644 (file)
@@ -28,7 +28,7 @@ IF(DEAL_II_COMPONENT_DOCUMENTATION)
   # Install the homepage:
   #
 
-  INSTALL(DIRECTORY .
+  INSTALL(DIRECTORY ${CMAKE_CURRENT_SOURCE_DIR}/
     DESTINATION ${DEAL_II_DOCUMENTATION_RELDIR}
     COMPONENT documentation
     FILES_MATCHING REGEX "^.*(html|css|eps|jpg|gif|fig|png|ico)$"
index 503577e068baefb20657fc5bab5e2b42221c7ec4..91c053f39776fa33401e294c8deaa6f967bf3d71 100644 (file)
@@ -46,14 +46,15 @@ CONFIGURE_FILE(
   )
 
 file(GLOB doxygen_input
-  # TODO: Steps
   ${CMAKE_SOURCE_DIR}/include/deal.II/*
   ${CMAKE_BINARY_DIR}/include/deal.II/*
   ${CMAKE_SOURCE_DIR}/doc/news/*.h
   ${CMAKE_SOURCE_DIR}/contrib/parameter_gui/*.h
   ${CMAKE_SOURCE_DIR}/contrib/parameter_gui/main.cpp
   ${CMAKE_CURRENT_SOURCE_DIR}/headers
+  ${CMAKE_CURRENT_BINARY_DIR}/tutorial
   )
+
 TO_STRING(doxygen_input ${doxygen_input})
 
 
@@ -82,3 +83,5 @@ ADD_CUSTOM_TARGET(doxygen ALL # TODO: Really all?
   VERBATIM
   )
 
+ADD_DEPENDENCIES(doxygen tutorial)
+
index bcaeccef5264c60067f939227f2ca115e554d3bd..230ea6e511b5345acf304e6ae97956324bdff76a 100644 (file)
@@ -477,7 +477,7 @@ EXCLUDE_PATTERNS       = *.templates.h
 # directories that contain example code fragments that are included (see
 # the \include command).
 
-EXAMPLE_PATH           = @CMAKE_SOURCE_DIR@/examples/doxygen @CMAKE_SOURCE_DIR@/doc/doxygen/tutorial/plain
+EXAMPLE_PATH           = @CMAKE_SOURCE_DIR@/examples/doxygen @CMAKE_BINARY_DIR@/doc/doxygen/tutorial
 
 # If the value of the EXAMPLE_PATH tag contains directories, you can use the
 # EXAMPLE_PATTERNS tag to specify one or more wildcard pattern (like *.cpp
index 423b65697525f7992c3626084fedad4fbb990dc5..7a8f2b479cb3319ce85705ecae6475aa042c38d9 100644 (file)
@@ -17,7 +17,7 @@
 # Prepare steps.png and steps.cmapx:
 #
 
-file(GLOB steps_args
+file(GLOB steps
   ${CMAKE_SOURCE_DIR}/examples/step-*
   )
 
@@ -26,7 +26,7 @@ ADD_CUSTOM_COMMAND(
   COMMAND ${PERL_EXECUTABLE}
   ARGS
     ${CMAKE_SOURCE_DIR}/doc/scripts/steps.pl
-    ${steps_args}
+    ${steps}
     > ${CMAKE_CURRENT_BINARY_DIR}/steps.dot
   )
 
@@ -67,13 +67,130 @@ ADD_CUSTOM_COMMAND(
     ${CMAKE_CURRENT_BINARY_DIR}/steps.cmapx
   )
 
-ADD_CUSTOM_TARGET(blubb ALL
+
+#
+# A target for the preparation of all the stuff happening in here...
+#
+ADD_CUSTOM_TARGET(tutorial
   DEPENDS
     ${CMAKE_CURRENT_BINARY_DIR}/toc.html
   )
 
 
 #
-# Prepare toc.html:
+# Prepare the steps for documentation generation
+#
+
+FOREACH(step ${steps})
+  GET_FILENAME_COMPONENT(step "${step}" NAME)
+  STRING(REGEX REPLACE "-" "_" step_underscore "${step}")
+
+  CONFIGURE_FILE(
+    ${CMAKE_CURRENT_SOURCE_DIR}/_toc.intro.snippet.in
+    ${CMAKE_CURRENT_BINARY_DIR}/${step}_toc.intro.snippet
+    )
+
+  CONFIGURE_FILE(
+    ${CMAKE_CURRENT_SOURCE_DIR}/_plain.snippet.in
+    ${CMAKE_CURRENT_BINARY_DIR}/${step}_plain.snippet
+    )
+
+  ADD_CUSTOM_COMMAND(
+    OUTPUT ${CMAKE_CURRENT_BINARY_DIR}/${step}.cc
+    COMMAND ${PERL_EXECUTABLE}
+    ARGS
+      ${CMAKE_SOURCE_DIR}/doc/scripts/program2plain
+      < ${CMAKE_SOURCE_DIR}/examples/${step}/${step}.cc
+      >> ${CMAKE_CURRENT_BINARY_DIR}/${step}.cc
+    DEPENDS
+      ${CMAKE_SOURCE_DIR}/examples/${step}/${step}.cc
+    VERBATIM
+    )
+
+  ADD_CUSTOM_COMMAND(
+    #
+    # This has to be refactored really, really badly...
+    #
+    OUTPUT ${CMAKE_CURRENT_BINARY_DIR}/${step}.h
+    COMMAND cat
+    ARGS
+      ${CMAKE_CURRENT_BINARY_DIR}/${step}_toc.intro.snippet
+      >> ${CMAKE_CURRENT_BINARY_DIR}/${step}.h
+    COMMAND ${PERL_EXECUTABLE}
+    ARGS
+      ${CMAKE_SOURCE_DIR}/doc/scripts/intro2toc
+      < ${CMAKE_SOURCE_DIR}/examples/${step}/doc/intro.dox
+      >> ${CMAKE_CURRENT_BINARY_DIR}/${step}.h
+    COMMAND cat
+    ARGS
+      ${CMAKE_CURRENT_SOURCE_DIR}/_toc.prog.snippet
+      >> ${CMAKE_CURRENT_BINARY_DIR}/${step}.h
+    COMMAND ${PERL_EXECUTABLE}
+    ARGS
+      ${CMAKE_SOURCE_DIR}/doc/scripts/program2toc
+      < ${CMAKE_SOURCE_DIR}/examples/${step}/${step}.cc
+      >> ${CMAKE_CURRENT_BINARY_DIR}/${step}.h
+    COMMAND cat
+    ARGS
+      ${CMAKE_CURRENT_SOURCE_DIR}/_toc.results.snippet
+      >> ${CMAKE_CURRENT_BINARY_DIR}/${step}.h
+    COMMAND ${PERL_EXECUTABLE}
+    ARGS
+      ${CMAKE_SOURCE_DIR}/doc/scripts/intro2toc
+      < ${CMAKE_SOURCE_DIR}/examples/${step}/doc/results.dox
+      >> ${CMAKE_CURRENT_BINARY_DIR}/${step}.h
+    COMMAND cat
+    ARGS
+      ${CMAKE_CURRENT_SOURCE_DIR}/_toc.final.snippet
+      >> ${CMAKE_CURRENT_BINARY_DIR}/${step}.h
+    COMMAND ${PERL_EXECUTABLE}
+    ARGS
+      ${CMAKE_SOURCE_DIR}/doc/scripts/create_anchors
+      < ${CMAKE_SOURCE_DIR}/examples/${step}/doc/intro.dox
+      >> ${CMAKE_CURRENT_BINARY_DIR}/${step}.h
+    COMMAND ${PERL_EXECUTABLE}
+    ARGS
+      ${CMAKE_SOURCE_DIR}/doc/scripts/program2doxygen
+      < ${CMAKE_SOURCE_DIR}/examples/${step}/${step}.cc
+      >> ${CMAKE_CURRENT_BINARY_DIR}/${step}.h
+    COMMAND ${PERL_EXECUTABLE}
+    ARGS
+      ${CMAKE_SOURCE_DIR}/doc/scripts/create_anchors
+      < ${CMAKE_SOURCE_DIR}/examples/${step}/doc/results.dox
+      >> ${CMAKE_CURRENT_BINARY_DIR}/${step}.h
+    COMMAND cat
+    ARGS
+      ${CMAKE_CURRENT_BINARY_DIR}/${step}_plain.snippet
+      >> ${CMAKE_CURRENT_BINARY_DIR}/${step}.h
+    WORKING_DIRECTORY
+      ${CMAKE_CURRENT_BINARY_DIR}
+    DEPENDS
+      ${CMAKE_SOURCE_DIR}/examples/${step}/${step}.cc
+      ${CMAKE_SOURCE_DIR}/examples/${step}/doc/intro.dox
+      ${CMAKE_SOURCE_DIR}/examples/${step}/doc/results.dox
+    VERBATIM
+    )
+  ADD_CUSTOM_TARGET(tutorial_${step}
+    DEPENDS
+      ${CMAKE_CURRENT_BINARY_DIR}/${step}.h
+      ${CMAKE_CURRENT_BINARY_DIR}/${step}.cc
+    )
+  ADD_DEPENDENCIES(tutorial tutorial_${step})
+ENDFOREACH()
+
+
+#
+# Install all bits:
 #
 
+INSTALL(FILES
+  index.html
+  navbar.html
+  title.html
+  toc-list.html #TODO
+  toc-topics.html #TODO
+  ${CMAKE_CURRENT_BINARY_DIR}/steps.png
+  ${CMAKE_CURRENT_BINARY_DIR}/toc.html
+  DESTINATION ${DEAL_II_DOCUMENTATION_RELDIR}/doxygen/tutorial
+  COMPONENT documentation
+  )
diff --git a/deal.II/doc/doxygen/tutorial/Makefile b/deal.II/doc/doxygen/tutorial/Makefile
deleted file mode 100644 (file)
index bcdebfe..0000000
+++ /dev/null
@@ -1,145 +0,0 @@
-$(example-toc-prog):
-       @echo ================== Making $@
-       @cat $D/examples/$(call get_basename, $@)/*.cc \
-         | $(PERL) program2toc \
-         > $@
-
-
-$(example-toc-plain):
-       @echo ================== Making $@
-       @cat generated/$(call get_basename, $@)_toc.prog \
-         | $(PERL) -pi -e 's/href=\"\#/href=\"\#plain-/g;' \
-         > $@
-
-
-$(example-toc-intro):
-       @echo ================== Making $@
-       @cat $D/examples/$(call get_basename, $@)/doc/intro.dox \
-         | egrep -i "<h[3456]>.*</h[3456]>" \
-         | $(PERL) ./intro2toc \
-         > $@
-
-
-$(example-toc-results):
-       @echo ================== Making $@
-       @cat $D/examples/$(call get_basename, $@)/doc/results.dox \
-         | egrep -i "<h[3456]>.*</h[3456]>" \
-         | $(PERL) ./intro2toc \
-         > $@
-
-
-$(example-toc):
-       @echo ================== Making $@
-       @echo "<table class=\"tutorial\" width=\"50%\">" > $@
-       @echo "<tr><th colspan=\"2\"><b><small>Table of contents</small></b></th></tr>" >> $@
-       @echo "<tr><td width=\"50%\" valign=\"top\">" >> $@
-       @echo "<ol>" >> $@
-       @echo "  <li> <a href=\"#Intro\" class=bold>Introduction</a>" >> $@
-       @cat generated/$(call get_basename, $@)_toc.intro >> $@
-       @echo "  <li> <a href=\"#CommProg\" class=bold>The commented program</a>" >> $@
-       @cat generated/$(call get_basename, $@)_toc.prog >> $@
-       @echo "</ol></td><td width=\"50%\" valign=\"top\"><ol>" >> $@
-       @echo "  <li value=\"3\"> <a href=\"#Results\" class=bold>Results</a>" >> $@
-       @cat generated/$(call get_basename, $@)_toc.results >> $@
-       @echo "  <li> <a href=\"#PlainProg\" class=bold>The plain program</a>" >> $@
-       @echo "</ol> </td> </tr> </table>" >> $@
-
-$(example-dox-prog):
-       @echo ================== Making $@
-       @mkdir -p generated
-       @cat $D/examples/$(call get_basename, $@)/*.cc \
-         | $(PERL) program2doxygen \
-         > $@
-
-$(example-plain):
-       @echo ================== Making $@
-       @mkdir -p plain
-       @cat $D/examples/$(call get_basename, $(@F))/*cc | $(PERL) program2plain > $@
-
-$(example-dox-plain):
-       @echo ================== Making $@
-       @echo " * <a name=\"PlainProg\"></a>" > $@
-       @echo " * <h1> The plain program</h1>" >> $@
-       @echo " * " >> $@
-       @echo " * (If you are looking at a locally installed deal.II version, then the" >> $@
-       @echo " * program can be found at <i>" >> $@
-       @echo " * " $D/examples/$(call get_basename,$@)/*.cc | $(PERL) -pi -e 's!/! /!g;' >> $@
-       @echo " * </i>. Otherwise, this is only" >> $@
-       @echo " * the path on some remote server.)" >> $@
-       @echo " @code" >> $@
-       @cat $D/examples/$(call get_basename, $@)/*.cc | $(PERL) program2doxyplain >> $@
-       @echo " @endcode" >> $@
-
-
-$(example-doxygen):
-       @echo ================== Assembling $@
-       @mkdir -p doxygen
-       @echo "/**" > $@
-       @echo " * @page $(shell echo $(call get_basename,$@) | $(PERL) -pi -e 's/-/_/g;') \
-                       The $(call get_basename,$@) tutorial program" >> $@
-       @echo "@htmlonly" >> $@
-       @cat generated/$(call get_basename, $@)_toc.combined >> $@
-       @echo "@endhtmlonly" >> $@
-       @cat $D/examples/$(call get_basename, $@)/doc/intro.dox \
-               | $(PERL) create_anchors >> $@
-       @echo >> $@
-       @cat generated/$(call get_basename, $@)_prog.dox >> $@
-       @cat $D/examples/$(call get_basename, $@)/doc/results.dox \
-               | $(PERL) create_anchors >> $@
-       @echo >> $@
-       @echo " <a name=\"PlainProg\"></a>" >> $@
-       @echo " <h1> The plain program</h1>" >> $@
-       @echo " @include \"$(call get_basename, $@).cc\"" >> $@
-       @echo " */" >> $@
-
-# Previous version of the lines after the last 'create_anchor'
-#      @cat generated/$(call get_basename, $@)_plain.dox >> $@
-
-validate-xrefs:
-       @$(PERL) $D/common/scripts/validate-xrefs.pl \
-                $(filter-out head.html foot.html, \
-                             $(shell echo *.html))
-
-
-clean:
-       -rm -f  plain/*.cc $(example-toc) \
-               $(example-toc-prog) $(example-toc-plain) \
-               $(example-toc-intro) $(example-toc-results) \
-               $(example-dox-prog) $(example-dox-plain) $(example-doxygen)
-       -rm -f Makefile.dep
-
-
-.PHONY: validate-xrefs clean
-
-
-Makefile.dep: $(shell echo $D/examples/*/*.cc $D/examples/*/doc/*.dox) Makefile
-       @echo ================== Generating $@
-       @for i in $(example-names) ; do \
-               echo generated/$${i}_prog.html generated/$${i}_plain.html \
-                    generated/$${i}_toc.prog \
-                    generated/$${i}_prog.dox generated/$${i}_plain.dox : \
-                       `echo $D/examples/$${i}/*.cc` ; \
-               echo generated/$${i}_toc.plain : generated/$${i}_toc.prog ; \
-               echo generated/$${i}_toc.combined : \
-                       generated/$${i}_toc.intro \
-                       generated/$${i}_toc.results \
-                       generated/$${i}_toc.prog \
-                       generated/$${i}_toc.plain ; \
-               echo plain/$$i.cc : `echo $D/examples/$${i}/*.cc` ; \
-               echo doxygen/$$i.h : generated/$${i}_prog.dox generated/$${i}_plain.dox \
-                               generated/$${i}_toc.combined \
-                               $D/examples/$$i/doc/intro.dox \
-                               $D/examples/$$i/doc/results.dox \
-                               plain/$$i.cc ; \
-               echo generated/$${i}_toc.intro : \
-                               $D/examples/$$i/doc/intro.dox \
-                        ; \
-               echo generated/$${i}_toc.results : \
-                               $D/examples/$$i/doc/results.dox \
-                        ; \
-        done \
-       > $@
-
-ifneq ($(CLEAN),yes)
-include Makefile.dep
-endif
diff --git a/deal.II/doc/doxygen/tutorial/_plain.snippet.in b/deal.II/doc/doxygen/tutorial/_plain.snippet.in
new file mode 100644 (file)
index 0000000..4c301e7
--- /dev/null
@@ -0,0 +1,4 @@
+<a name="PlainProg"></a>
+<h1> The plain program</h1>
+@include "${step}.cc"
+ */
diff --git a/deal.II/doc/doxygen/tutorial/_toc.final.snippet b/deal.II/doc/doxygen/tutorial/_toc.final.snippet
new file mode 100644 (file)
index 0000000..ccfc936
--- /dev/null
@@ -0,0 +1,3 @@
+  <li> <a href="#PlainProg" class=bold>The plain program</a>
+</ol> </td> </tr> </table>
+@endhtmlonly
diff --git a/deal.II/doc/doxygen/tutorial/_toc.intro.snippet.in b/deal.II/doc/doxygen/tutorial/_toc.intro.snippet.in
new file mode 100644 (file)
index 0000000..81d35a5
--- /dev/null
@@ -0,0 +1,8 @@
+/**
+  * @page ${step_underscore} The ${step} tutorial program
+@htmlonly
+<table class="tutorial" width="50%">
+<tr><th colspan="2"><b><small>Table of contents</small></b></th></tr>
+<tr><td width="50%" valign="top">
+<ol>
+  <li> <a href="#Intro" class=bold>Introduction</a>
diff --git a/deal.II/doc/doxygen/tutorial/_toc.prog.snippet b/deal.II/doc/doxygen/tutorial/_toc.prog.snippet
new file mode 100644 (file)
index 0000000..c582c11
--- /dev/null
@@ -0,0 +1 @@
+  <li> <a href="#CommProg" class=bold>The commented program</a>
diff --git a/deal.II/doc/doxygen/tutorial/_toc.results.snippet b/deal.II/doc/doxygen/tutorial/_toc.results.snippet
new file mode 100644 (file)
index 0000000..3325e2a
--- /dev/null
@@ -0,0 +1,2 @@
+</ol></td><td width="50%" valign="top"><ol>
+  <li value="3"> <a href="#Results" class=bold>Results</a>
index 3f6b340f5032cb4cafe90628c6d5d37b928e586c..53839ab09a6f601371f960102b390436e4eb9b9e 100644 (file)
@@ -18,51 +18,48 @@ while (<>) {
     if ( /<h(.)>(.*)<\/h.>\s*/ ) {
        $newlevel = $1;
        $text = $2;
-       
        # only allow header levels 3 through 6, since higher ones are
        # reserved for top-level document headers
-       if (! ($newlevel =~ /[3456]/)) {
-           print STDERR "Only header levels 3 through 6 are allowed.\n";
-           print STDERR "You had $newlevel.\n";
-           die;
-       }
+        #
+       if (($newlevel =~ /[3456]/)) {
 
-       if ($newlevel > $level) {
-           for ($i=$level; $i<$newlevel; ++$i) {
-               print "      <ul>\n";
-            }
-       } elsif ($newlevel < $level) {
-           for ($i=$newlevel; $i<$level; ++$i) {
-               print "      </ul>\n";
-            }
-       }
+          if ($newlevel > $level) {
+              for ($i=$level; $i<$newlevel; ++$i) {
+                  print "      <ul>\n";
+              }
+          } elsif ($newlevel < $level) {
+              for ($i=$newlevel; $i<$level; ++$i) {
+                  print "      </ul>\n";
+              }
+          }
 
-       $reftext = $text;
+          $reftext = $text;
 
-       # for the anchor, use the name of the section but discard
-       # everything except for letters, numbers, and underscores
-       $reftext =~ s/[^a-zA-Z0-9_]//g;
+          # for the anchor, use the name of the section but discard
+          # everything except for letters, numbers, and underscores
+          $reftext =~ s/[^a-zA-Z0-9_]//g;
 
-       # replace quotation marks by the appropriate HTML quotation marks
-       $text =~ s!``!&#8220;!g;
-       $text =~ s!''!&#8221;!g;
+          # replace quotation marks by the appropriate HTML quotation marks
+          $text =~ s!``!&#8220;!g;
+          $text =~ s!''!&#8221;!g;
 
-        # replace double dashes in comments by &mdash;
-       $text =~ s!--!&mdash;!g;
+          # replace double dashes in comments by &mdash;
+          $text =~ s!--!&mdash;!g;
 
-       # we sometimes escape words with % (as in "%Boundary
-        # conditions") because doxygen would otherwise link the word
-        # to a class name. This isn't necessary in the index because
-        # the text already appears in a hyperref, so get rid of the
-        # percent sign
-       $text =~ s!\%!!g;
+          # we sometimes escape words with % (as in "%Boundary
+          # conditions") because doxygen would otherwise link the word
+          # to a class name. This isn't necessary in the index because
+          # the text already appears in a hyperref, so get rid of the
+          # percent sign
+          $text =~ s!\%!!g;
 
-       print "        <li><a href=\"#$reftext\">$text</a>\n";
+          print "        <li><a href=\"#$reftext\">$text</a>\n";
 
-       $level = $newlevel;
-    } 
+          $level = $newlevel;
+       }
+    }
 }
 
 for (; $level>=3; --$level) {
-    print "      </ul>\n";
+    print "    </ul>\n";
 }

In the beginning the Universe was created. This has made a lot of people very angry and has been widely regarded as a bad move.

Douglas Adams


Typeset in Trocchi and Trocchi Bold Sans Serif.