Merge #3304

3304: Use BibTeX citations in Doxygen r=fweik a=jngrad

Follow-up to the Summer School developers meeting

Description of changes:
- replace all hardcoded literature references in the core by BibTeX references (817e59b)
- backport improvements from 4.1.1: grammar and spell check, copyright years
- remove unit tests from the doxygen documentation (too much clutter)
- cleanup doxygen documentation

Co-authored-by: Jean-Noël Grad <jgrad@icp.uni-stuttgart.de>

.gitlab-ci.yml

@@ -472,9 +472,9 @@ run_tutorials:
 run_doxygen:
   <<: *global_job_definition
   stage: additional_checks
-  image: gitlab.icp.uni-stuttgart.de:4567/espressomd/docker/ubuntu-python3:cuda-9.0
+  image: gitlab.icp.uni-stuttgart.de:4567/espressomd/docker/ubuntu-python3:cuda-10.1
   needs:
-    - cuda9-maxset
+    - cuda10-maxset
   when: on_success
   only:
     - python

doc/doxygen/CMakeLists.txt

@@ -7,6 +7,17 @@ if(DOXYGEN_FOUND)
     DEPENDS EspressoConfig
   )
 
+  # transform BibTeX DOI fields into URL fields (bibliographic
+  # styles available to Doxygen do not process the DOI field)
+  add_custom_command(
+    OUTPUT ${CMAKE_CURRENT_BINARY_DIR}/bibliography.bib
+    COMMAND sed -r
+     "'s_^ *doi *= *([^0-9]+)(10\\.[0-9]+)_url=\\1https://dx.doi.org/\\2_'"
+     ${CMAKE_CURRENT_SOURCE_DIR}/bibliography.bib >
+     ${CMAKE_CURRENT_BINARY_DIR}/bibliography.bib
+    DEPENDS ${CMAKE_CURRENT_SOURCE_DIR}/bibliography.bib
+  )
+
   set(DOXYGEN_IN ${CMAKE_CURRENT_SOURCE_DIR}/Doxyfile.in)
   set(DOXYGEN_OUT ${CMAKE_CURRENT_BINARY_DIR}/Doxyfile)
 
@@ -17,6 +28,7 @@ if(DOXYGEN_FOUND)
     WORKING_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}
     COMMENT "Generating API documentation with Doxygen"
     DEPENDS ${CMAKE_CURRENT_BINARY_DIR}/doxy-features
+            ${CMAKE_CURRENT_BINARY_DIR}/bibliography.bib
     VERBATIM
   )
 

doc/doxygen/Doxyfile.in

@@ -585,7 +585,7 @@ LAYOUT_FILE            =
 # of the bibliography can be controlled using LATEX_BIB_STYLE. To use this
 # feature you need bibtex and perl available in the search path.
 
-CITE_BIB_FILES         =
+CITE_BIB_FILES         = bibliography.bib
 
 #---------------------------------------------------------------------------
 # configuration options related to warning and progress messages
@@ -700,7 +700,8 @@ EXCLUDE_SYMLINKS       = NO
 # against the file with absolute path, so to exclude all test directories
 # for example use the pattern */test/*
 
-EXCLUDE_PATTERNS       =
+EXCLUDE_PATTERNS       = @CMAKE_SOURCE_DIR@/*/unit_tests/* \
+                         @CMAKE_SOURCE_DIR@/*/tests/*
 
 # The EXCLUDE_SYMBOLS tag can be used to specify one or more symbol names
 # (namespaces, classes, functions, etc.) that should be excluded from the
@@ -1315,7 +1316,7 @@ LATEX_SOURCE_CODE      = NO
 # bibliography, e.g. plainnat, or ieeetr. The default style is "plain". See
 # http://en.wikipedia.org/wiki/BibTeX for more info.
 
-LATEX_BIB_STYLE        = plain
+LATEX_BIB_STYLE        = plainnat
 
 #---------------------------------------------------------------------------
 # configuration options related to the RTF output