Merge pull request #3197 from eseiler/infra/doxygen

[INFRA] Doxygen

.github/workflows/ci_documentation.yml

@@ -50,7 +50,7 @@ jobs:
       - name: Install Doxygen
         uses: seqan/actions/setup-doxygen@main
         with:
-          doxygen: 1.9.6
+          doxygen: 1.9.8
 
       - name: Configure tests
         run: |

.github/workflows/deploy_documentation.yaml

@@ -36,13 +36,13 @@ jobs:
       - name: Install Doxygen
         uses: seqan/actions/setup-doxygen@main
         with:
-          doxygen: 1.9.6
+          doxygen: 1.9.8
 
       - name: Load cached documentation
         uses: actions/cache@v3
         with:
           path: doc-build
-          key: ${{ runner.os }}-documentation-1.9.6
+          key: ${{ runner.os }}-documentation-1.9.8
 
       - name: Build documentation
         run: |

CHANGELOG.md

@@ -24,6 +24,17 @@ The following API changes should be documented as such:
 If possible, provide tooling that performs the changes, e.g. a shell-script.
 -->
 
+# 3.3.1
+
+## New features
+
+## Notable Bug-fixes
+
+## API changes
+
+#### Dependencies
+  * We now use Doxygen version 1.9.8 to build our documentation ([\#3197](https://github.com/seqan/seqan3/pull/3197)).
+
 # 3.3.0
 
 ## New features

include/seqan3/alignment/aligned_sequence/debug_stream_alignment.hpp

@@ -26,7 +26,7 @@ namespace seqan3::detail
 {
 
 /*!\brief               Create the formatted alignment output and add it to the provided debug_stream.
- * \ingroup             aligned_sequence
+ * \ingroup             alignment_aligned_sequence
  * \tparam alignment_t  The type of the alignment; must model seqan3::tuple_like.
  * \tparam idx          An index sequence.
  * \param[in] stream    The output stream that receives the formatted alignment.

include/seqan3/alignment/matrix/all.hpp

@@ -6,18 +6,15 @@
 // -----------------------------------------------------------------------------------------------------
 
 /*!\file
- * \brief Meta-header for the \cond DEV \link alignment_matrix Alignment / Matrix submodule \endlink \endcond.
+ * \brief Meta-header for the \link alignment_matrix Alignment / Matrix submodule \endlink.
  * \author Marcel Ehrhardt <marcel.ehrhardt AT fu-berlin.de>
  */
 
-//!\cond DEV
-
 /*!\defgroup alignment_matrix Matrix
  * \brief Provides data structures for representing alignment coordinates and alignments as a matrix.
  * \ingroup alignment
  * \see alignment
  */
-//!\endcond
 
 #pragma once
 

include/seqan3/alignment/pairwise/alignment_algorithm.hpp

@@ -62,8 +62,8 @@ namespace seqan3::detail
  * using SIMD operations or scalar operations, computing the traceback or only the score etc.. These configurations
  * are inherited using so-called `alignment policies`. An alignment policy is a type that implements a specific
  * functionality through a common interface that is used by the alignment algorithm. These policies are also
- * the customisation points of the algorithm which will be used to implement a specific behaviour. You can read more
- * about the policies in \ref alignment_pairwise_policy.
+ * the customisation points of the algorithm which will be used to implement a specific behaviour. \if DEV You can read
+ * more about the policies in \ref alignment_pairwise_policy. \endif
  *
  * Since some of the policies are augmented with traits to further refine the policy execution during the configuration,
  * it is necessary to defer the template instantiation of the policies, which are modelled as CRTP-base classes.

include/seqan3/utility/simd/all.hpp

@@ -7,25 +7,20 @@
 
 /*!\file
  * \author Marcel Ehrhardt <marcel.ehrhardt AT fu-berlin.de>
- * \brief Meta-header for the \cond DEV \link utility_simd Utility / SIMD submodule \endlink \endcond.
+ * \brief Meta-header for the \link utility_simd Utility / SIMD submodule \endlink.
  */
 
-//!\cond DEV
-
 /*!\defgroup utility_simd SIMD
  * \brief The simd module contains a unified interface to provide simd types and functions used in seqan3.
  * \ingroup utility
  * \see utility
  * \see https://en.wikipedia.org/wiki/SIMD
  *
- * \todo Make this public again. We made this documentation internal-documentation only for the 3.0.0 release, because
- * the API was not in shape yet. Remove the `cond DEV` and `todo` commands and remove `seqan3::simd` from
- * SEQAN3_DOXYGEN_EXCLUDE_SYMBOLS in `seqan3-doxygen.cmake`.
- *
  * There are different simd implementations (backends), which are auto-selected by seqan3::simd::simd_type_t.
- * \if DEV
  * Namely seqan3::detail::builtin_simd.
- * \endif
+ *
+ * \todo Make this public again. We made this documentation internal-documentation only for the 3.0.0 release, because
+ * the API was not in shape yet. Remove /utility/simd/ exclusion from EXCLUDE_PATTERNS.
  *
  * \todo Describe more what SIMD is and how to use it.
  */
@@ -35,7 +30,6 @@
  * \sa https://en.wikipedia.org/wiki/SIMD What is SIMD conceptually?
  * \sa https://en.wikipedia.org/wiki/Streaming_SIMD_Extensions Which SIMD architectures exist?
  */
-//!\endcond
 
 #pragma once
 

include/seqan3/utility/simd/detail/debug_stream_simd.hpp

@@ -22,10 +22,6 @@ namespace seqan3
 
 /*!\brief Overload for debug_stream for simd types.
  * \ingroup utility_simd
- * \private
- * \todo Make this public again. We made this documentation internal-documentation only for the 3.0.0 release, because
- * the API was not in shape yet. Remove the `private` and `todo` commands and remove `seqan3::simd` from
- * SEQAN3_DOXYGEN_EXCLUDE_SYMBOLS in `seqan3-doxygen.cmake`.
  */
 template <typename char_t, typename simd_t>
     requires simd::simd_concept<std::remove_cvref_t<simd_t>>

include/seqan3/utility/simd/views/all.hpp

@@ -6,20 +6,16 @@
 // -----------------------------------------------------------------------------------------------------
 
 /*!\file
- * \brief Meta-header for the \cond DEV \link utility_simd_views Utility / SIMD / Views submodule \endlink \endcond.
+ * \brief Meta-header for the \link utility_simd_views Utility / SIMD / Views submodule \endlink.
  * \author Marcel Ehrhardt <marcel.ehrhardt AT fu-berlin.de>
  */
 
-//!\cond DEV
-
 /*!\defgroup utility_simd_views Views
  * \brief SIMD related views.
  * \ingroup utility_simd
  * \see utility_simd
  */
 
-//!\endcond
-
 #pragma once
 
 #include <seqan3/utility/simd/views/iota_simd.hpp>

test/documentation/.vercel/install.sh

@@ -1,7 +1,7 @@
 #!/usr/bin/env bash
 set -exo pipefail
 
-DOXYGEN_VERSION=1.9.6
+DOXYGEN_VERSION=1.9.8
 SOURCE_DIR=`pwd`
 CACHE_DIR="${SOURCE_DIR}/node_modules"
 

test/documentation/DoxygenLayout.xml

@@ -1,5 +1,6 @@
+<?xml version="1.0" encoding="UTF-8"?>
 <doxygenlayout version="1.0">
-  <!-- Generated by doxygen 1.9.6 -->
+  <!-- Generated by doxygen 1.9.8 -->
   <!-- Navigation index tabs for HTML output -->
   <navindex>
     <tab type="mainpage" visible="yes" title="Welcome"/>
@@ -21,8 +22,12 @@
       <tab type="user" visible="yes" title="Code of Conduct" url="\ref about_code_of_conduct" intro=""/>
       <tab type="user" visible="yes" title="Contributing" url="\ref about_contributing" intro=""/>
     </tab>
-    <tab type="modules" visible="yes" title="API Reference" intro=""/>
+    <tab type="topics" visible="yes" title="API Reference" intro=""/>
     <tab type="usergroup" visible="${SEQAN3_SHOW_DEV_DOCS}" title="API Reference (details)" intro="">
+      <tab type="modules" visible="no" title="" intro="">
+        <tab type="modulelist" visible="yes" title="" intro=""/>
+        <tab type="modulemembers" visible="yes" title="" intro=""/>
+      </tab>
       <tab type="namespaces" visible="yes" title="">
         <tab type="namespacelist" visible="yes" title="" intro=""/>
         <tab type="namespacemembers" visible="yes" title="" intro=""/>
@@ -201,6 +206,7 @@
     <groupgraph visible="$GROUP_GRAPHS"/>
     <memberdecl>
       <nestedgroups visible="yes" title=""/>
+      <modules visible="yes" title=""/>
       <dirs visible="yes" title=""/>
       <files visible="yes" title=""/>
       <namespaces visible="yes" title=""/>
@@ -246,6 +252,25 @@
     <authorsection visible="yes"/>
   </group>
 
+  <!-- Layout definition for a C++20 module page -->
+  <module>
+    <briefdescription visible="yes"/>
+    <exportedmodules visible="yes"/>
+    <memberdecl>
+      <concepts visible="yes" title=""/>
+      <classes visible="yes" title=""/>
+      <enums title=""/>
+      <typedefs title=""/>
+      <functions title=""/>
+      <variables title=""/>
+      <membergroups title=""/>
+    </memberdecl>
+    <detaileddescription title=""/>
+    <memberdecl>
+      <files visible="yes"/>
+    </memberdecl>
+  </module>
+
   <!-- Layout definition for a directory page -->
   <directory>
     <briefdescription visible="yes"/>

test/documentation/doc_usr/CMakeLists.txt

@@ -8,7 +8,7 @@
 message (STATUS "Configuring user doc.")
 
 set (SEQAN3_DOXYGEN_OUTPUT_DIR "${CMAKE_CURRENT_BINARY_DIR}")
-set (SEQAN3_DOXYGEN_EXCLUDE_SYMBOLS "detail seqan3::simd") #/""
+set (SEQAN3_DOXYGEN_EXCLUDE_SYMBOLS "")
 set (SEQAN3_DOXYGEN_PREDEFINED_NDEBUG "-NDEBUG") #/""
 set (SEQAN3_DOXYGEN_ENABLED_SECTIONS "") #/"DEV"
 set (SEQAN3_SHOW_DEV_DOCS "NO") #/"YES"

test/documentation/seqan3_doxygen_cfg.in

@@ -1,4 +1,4 @@
-# Doxyfile 1.9.6
+# Doxyfile 1.9.8
 
 #---------------------------------------------------------------------------
 # Project related configuration options
@@ -69,6 +69,7 @@ OPTIMIZE_OUTPUT_SLICE  = NO
 EXTENSION_MAPPING      = .no_extension=C++
 MARKDOWN_SUPPORT       = YES
 TOC_INCLUDE_HEADINGS   = 2
+MARKDOWN_ID_STYLE      = DOXYGEN
 AUTOLINK_SUPPORT       = YES
 BUILTIN_STL_SUPPORT    = NO
 CPP_CLI_SUPPORT        = NO
@@ -82,6 +83,7 @@ INLINE_SIMPLE_STRUCTS  = NO
 TYPEDEF_HIDES_STRUCT   = NO
 LOOKUP_CACHE_SIZE      = 0
 NUM_PROC_THREADS       = 1
+TIMESTAMP              = YES
 #---------------------------------------------------------------------------
 # Build related configuration options
 #---------------------------------------------------------------------------
@@ -155,7 +157,8 @@ RECURSIVE              = YES
 EXCLUDE                =
 EXCLUDE_SYMLINKS       = NO
 EXCLUDE_PATTERNS       = */doc/*.cpp \
-                         */contrib/std/*.hpp
+                         */contrib/std/*.hpp \
+                         */utility/simd/*.hpp
 EXCLUDE_SYMBOLS        = seqan3::contrib \
                          ${SEQAN3_DOXYGEN_EXCLUDE_SYMBOLS}
 EXAMPLE_PATH           = ${SEQAN3_DOXYGEN_SOURCE_DIR}
@@ -210,9 +213,9 @@ HTML_COLORSTYLE        = LIGHT
 HTML_COLORSTYLE_HUE    = 209
 HTML_COLORSTYLE_SAT    = 255
 HTML_COLORSTYLE_GAMMA  = 113
-HTML_TIMESTAMP         = YES
 HTML_DYNAMIC_MENUS     = YES
 HTML_DYNAMIC_SECTIONS  = YES
+HTML_CODE_FOLDING      = YES
 HTML_INDEX_NUM_ENTRIES = 100
 GENERATE_DOCSET        = NO
 DOCSET_FEEDNAME        = "Doxygen generated docs"
@@ -227,6 +230,7 @@ GENERATE_CHI           = NO
 CHM_INDEX_ENCODING     =
 BINARY_TOC             = NO
 TOC_EXPAND             = NO
+SITEMAP_URL            =
 GENERATE_QHP           = NO
 QCH_FILE               =
 QHP_NAMESPACE          = org.doxygen.Project
@@ -280,7 +284,6 @@ USE_PDFLATEX           = YES
 LATEX_BATCHMODE        = NO
 LATEX_HIDE_INDICES     = NO
 LATEX_BIB_STYLE        = plain
-LATEX_TIMESTAMP        = NO
 LATEX_EMOJI_DIRECTORY  =
 #---------------------------------------------------------------------------
 # Configuration options related to the RTF output
@@ -316,6 +319,12 @@ DOCBOOK_OUTPUT         = docbook
 #---------------------------------------------------------------------------
 GENERATE_AUTOGEN_DEF   = NO
 #---------------------------------------------------------------------------
+# Configuration options related to Sqlite3 output
+#---------------------------------------------------------------------------
+GENERATE_SQLITE3       = NO
+SQLITE3_OUTPUT         = sqlite3
+SQLITE3_RECREATE_DB    = YES
+#---------------------------------------------------------------------------
 # Configuration options related to the Perl module output
 #---------------------------------------------------------------------------
 GENERATE_PERLMOD       = NO
@@ -352,9 +361,8 @@ ALLEXTERNALS           = NO
 EXTERNAL_GROUPS        = YES
 EXTERNAL_PAGES         = YES
 #---------------------------------------------------------------------------
-# Configuration options related to the dot tool
+# Configuration options related to diagram generator tools
 #---------------------------------------------------------------------------
-DIA_PATH               =
 HIDE_UNDOC_RELATIONS   = YES
 ## DOT SUPPORT
 HAVE_DOT               = ${SEQAN3_DOXYGEN_HAVE_DOT}
@@ -382,7 +390,7 @@ DOT_IMAGE_FORMAT       = svg
 INTERACTIVE_SVG        = ${SEQAN3_DOXYGEN_HAVE_DOT}
 DOT_PATH               =
 DOTFILE_DIRS           =
-MSCFILE_DIRS           =
+DIA_PATH               =
 DIAFILE_DIRS           =
 PLANTUML_JAR_PATH      =
 PLANTUML_CFG_FILE      =
@@ -392,6 +400,8 @@ MAX_DOT_GRAPH_DEPTH    = 0
 DOT_MULTI_TARGETS      = NO
 GENERATE_LEGEND        = YES
 DOT_CLEANUP            = YES
+MSCGEN_TOOL            =
+MSCFILE_DIRS           =
 #---------------------------------------------------------------------------
 # Configuration options related to the deployment by Vercel
 #---------------------------------------------------------------------------

test/documentation/seqan3_footer.html.in

@@ -1,4 +1,4 @@
-<!-- HTML footer for doxygen 1.9.6-->
+<!-- HTML footer for doxygen 1.9.8-->
 <!-- start footer part -->
 <!--BEGIN GENERATE_TREEVIEW-->
 <script type="text/javascript" charset="utf-8" src="api-stability.js"></script>

test/documentation/seqan3_header.html

@@ -1,4 +1,4 @@
-<!-- HTML header for doxygen 1.9.6-->
+<!-- HTML header for doxygen 1.9.8-->
 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "https://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
 <html xmlns="http://www.w3.org/1999/xhtml" lang="$langISO">
 <head>