From: maier Date: Mon, 8 Oct 2012 23:30:09 +0000 (+0000) Subject: *Yay* Add support for building the doxygen documentation X-Git-Url: https://gitweb.dealii.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=b5e3b5c6de8434d0ed83ad1f018b13f694ea4f1d;p=dealii-svn.git *Yay* Add support for building the doxygen documentation git-svn-id: https://svn.dealii.org/branches/branch_cmake@27017 0785d39b-7218-0410-832d-ea1e28bc413d --- diff --git a/deal.II/TODO.CMAKE b/deal.II/TODO.CMAKE index 1c935cc027..2773ec5410 100644 --- a/deal.II/TODO.CMAKE +++ b/deal.II/TODO.CMAKE @@ -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 diff --git a/deal.II/doc/CMakeLists.txt b/deal.II/doc/CMakeLists.txt index 3e846328b3..c09c7dfeed 100644 --- a/deal.II/doc/CMakeLists.txt +++ b/deal.II/doc/CMakeLists.txt @@ -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)$" diff --git a/deal.II/doc/doxygen/CMakeLists.txt b/deal.II/doc/doxygen/CMakeLists.txt index 503577e068..91c053f397 100644 --- a/deal.II/doc/doxygen/CMakeLists.txt +++ b/deal.II/doc/doxygen/CMakeLists.txt @@ -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) + diff --git a/deal.II/doc/doxygen/options.dox.in b/deal.II/doc/doxygen/options.dox.in index bcaeccef52..230ea6e511 100644 --- a/deal.II/doc/doxygen/options.dox.in +++ b/deal.II/doc/doxygen/options.dox.in @@ -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 diff --git a/deal.II/doc/doxygen/tutorial/CMakeLists.txt b/deal.II/doc/doxygen/tutorial/CMakeLists.txt index 423b656975..7a8f2b479c 100644 --- a/deal.II/doc/doxygen/tutorial/CMakeLists.txt +++ b/deal.II/doc/doxygen/tutorial/CMakeLists.txt @@ -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 index bcdebfe83d..0000000000 --- a/deal.II/doc/doxygen/tutorial/Makefile +++ /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 ".*" \ - | $(PERL) ./intro2toc \ - > $@ - - -$(example-toc-results): - @echo ================== Making $@ - @cat $D/examples/$(call get_basename, $@)/doc/results.dox \ - | egrep -i ".*" \ - | $(PERL) ./intro2toc \ - > $@ - - -$(example-toc): - @echo ================== Making $@ - @echo "" > $@ - @echo "" >> $@ - @echo "
Table of contents
" >> $@ - @echo "
    " >> $@ - @echo "
  1. Introduction" >> $@ - @cat generated/$(call get_basename, $@)_toc.intro >> $@ - @echo "
  2. The commented program" >> $@ - @cat generated/$(call get_basename, $@)_toc.prog >> $@ - @echo "
    " >> $@ - @echo "
  1. Results" >> $@ - @cat generated/$(call get_basename, $@)_toc.results >> $@ - @echo "
  2. The plain program" >> $@ - @echo "
" >> $@ - -$(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 " * " > $@ - @echo " *

The plain program

" >> $@ - @echo " * " >> $@ - @echo " * (If you are looking at a locally installed deal.II version, then the" >> $@ - @echo " * program can be found at " >> $@ - @echo " * " $D/examples/$(call get_basename,$@)/*.cc | $(PERL) -pi -e 's!/! /!g;' >> $@ - @echo " * . 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 " " >> $@ - @echo "

The plain program

" >> $@ - @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 index 0000000000..4c301e7158 --- /dev/null +++ b/deal.II/doc/doxygen/tutorial/_plain.snippet.in @@ -0,0 +1,4 @@ + +

The plain program

+@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 index 0000000000..ccfc93656c --- /dev/null +++ b/deal.II/doc/doxygen/tutorial/_toc.final.snippet @@ -0,0 +1,3 @@ +
  • The plain program + +@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 index 0000000000..81d35a5b04 --- /dev/null +++ b/deal.II/doc/doxygen/tutorial/_toc.intro.snippet.in @@ -0,0 +1,8 @@ +/** + * @page ${step_underscore} The ${step} tutorial program +@htmlonly + + +
    Table of contents
    +
      +
    1. Introduction diff --git a/deal.II/doc/doxygen/tutorial/_toc.prog.snippet b/deal.II/doc/doxygen/tutorial/_toc.prog.snippet new file mode 100644 index 0000000000..c582c111d0 --- /dev/null +++ b/deal.II/doc/doxygen/tutorial/_toc.prog.snippet @@ -0,0 +1 @@ +
    2. The commented program diff --git a/deal.II/doc/doxygen/tutorial/_toc.results.snippet b/deal.II/doc/doxygen/tutorial/_toc.results.snippet new file mode 100644 index 0000000000..3325e2adac --- /dev/null +++ b/deal.II/doc/doxygen/tutorial/_toc.results.snippet @@ -0,0 +1,2 @@ +
      +
    1. Results diff --git a/deal.II/doc/scripts/intro2toc b/deal.II/doc/scripts/intro2toc index 3f6b340f50..53839ab09a 100644 --- a/deal.II/doc/scripts/intro2toc +++ b/deal.II/doc/scripts/intro2toc @@ -18,51 +18,48 @@ while (<>) { if ( /(.*)<\/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 "
        \n"; - } - } elsif ($newlevel < $level) { - for ($i=$newlevel; $i<$level; ++$i) { - print "
      \n"; - } - } + if ($newlevel > $level) { + for ($i=$level; $i<$newlevel; ++$i) { + print "
        \n"; + } + } elsif ($newlevel < $level) { + for ($i=$newlevel; $i<$level; ++$i) { + print "
      \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!``!“!g; - $text =~ s!''!”!g; + # replace quotation marks by the appropriate HTML quotation marks + $text =~ s!``!“!g; + $text =~ s!''!”!g; - # replace double dashes in comments by — - $text =~ s!--!—!g; + # replace double dashes in comments by — + $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; + # 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 "
    2. $text\n"; + print "
    3. $text\n"; - $level = $newlevel; - } + $level = $newlevel; + } + } } for (; $level>=3; --$level) { - print " \n"; + print " \n"; }