Add doxygen-check pre-commit hook (#11076)

- Adds doxygen-check pre-commit hook (verbose) - doxygen-check passes with warning if doxygen is not present - doxygen-check passes with warning if supported doxygen version 1.8.20 to 1.9.1 is not present - doxygen-check fails if any warning or error is thrown by doxygen - since pre-commit runs as part of style check, it's removed from _style.sh_ - updated Doxyfile configuration to work with versions 1.8.20 to 1.9.1 - added doxygen=1.8.20 to conda dev environment - mentioned doxygen.sh in CONTRIBUTING.md guide Related to #9373 (Add Doxygen CI check) Authors: - Karthikeyan (https://github.com/karthikeyann) Approvers: - Bradley Dice (https://github.com/bdice) - Yunsong Wang (https://github.com/PointKernel) - AJ Schmidt (https://github.com/ajschmidt8) URL: #11076
rapidsai · Jun 20, 2022 · ff1f9d3 · ff1f9d3
1 parent 0fe5d2d
commit ff1f9d3
Show file tree

Hide file tree

Showing 6 changed files with 93 additions and 75 deletions.
diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
@@ -101,6 +101,14 @@ repos:
                 stages: [commit]
                 entry: python ./ci/checks/copyright.py --git-modified-only
                 language: python
+              - id: doxygen-check
+                name: doxygen-check
+                entry: ./ci/checks/doxygen.sh
+                files: ^cpp/include/
+                types_or: [file]
+                language: system
+                pass_filenames: false
+                verbose: true
 
 default_language_version:
       python: python3
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -339,6 +339,12 @@ python3 ./cpp/scripts/run-clang-format.py -inplace
 Additionally, many editors have plugins or extensions that you can set up to automatically run
 `clang-format` either manually or on file save.
 
+[`doxygen`](https://doxygen.nl/) is used as documentation generator and also as a documentation linter.
+In order to run doxygen as linter on C++/CUDA code, run
+```bash
+./ci/checks/doxygen.sh
+```
+
 ### Python / Pre-commit hooks
 
 cuDF uses [pre-commit](https://pre-commit.com/) to execute code linters and formatters such as

diff --git a/ci/checks/doxygen.sh b/ci/checks/doxygen.sh
@@ -0,0 +1,35 @@
+#!/bin/bash
+# Copyright (c) 2022, NVIDIA CORPORATION.
+###############################
+# cuDF doxygen warnings check #
+###############################
+
+# skip if doxygen is not installed
+if ! [ -x "$(command -v doxygen)" ]; then
+  echo -e "warning: doxygen is not installed"
+  exit 0
+fi
+
+# Utility to return version as number for comparison
+function version { echo "$@" | awk -F. '{ printf("%d%03d%03d%03d\n", $1,$2,$3,$4); }'; }
+
+# doxygen supported version 1.8.20 to 1.9.1
+DOXYGEN_VERSION=`doxygen --version`
+if [ $(version "$DOXYGEN_VERSION") -lt $(version "1.8.20") ] ||  [ $(version $DOXYGEN_VERSION) -gt $(version "1.9.1") ]; then
+  echo -e "warning: Unsupported doxygen version $DOXYGEN_VERSION"
+  echo -e "Expecting doxygen version from 1.8.20 to 1.9.1"
+  exit 0
+fi
+
+# Run doxygen, ignore missing tag files error
+TAG_ERROR1="error: Tag file '.*.tag' does not exist or is not a file. Skipping it..."
+TAG_ERROR2="error: cannot open tag file .*.tag for writing"
+DOXYGEN_STDERR=`cd cpp/doxygen && { cat Doxyfile ; echo QUIET = YES; echo GENERATE_HTML = NO; }  | doxygen - 2>&1 | sed "/\($TAG_ERROR1\|$TAG_ERROR2\)/d"`
+RETVAL=$?
+
+if [ "$RETVAL" != "0" ] || [ ! -z "$DOXYGEN_STDERR" ]; then
+  echo -e "$DOXYGEN_STDERR"
+  RETVAL=1 #because return value is not generated by doxygen 1.8.20
+fi
+
+exit $RETVAL
diff --git a/ci/checks/style.sh b/ci/checks/style.sh
@@ -54,21 +54,8 @@ HEADER_META=`ci/checks/headers_test.sh`
 HEADER_META_RETVAL=$?
 echo -e "$HEADER_META"
 
-# Run doxygen and check for missing documentation
-DOXYGEN=`cd cpp/doxygen && { cat Doxyfile ; echo QUIET = YES; echo GENERATE_HTML = NO; }  | doxygen - 2>&1 | tail -n +3`
-DOXYGEN_RETVAL=$?
-
-if [ "$DOXYGEN_RETVAL" != "0" ] || [ ! -z "$DOXYGEN" ]; then
-  echo -e "\n\n>>>> FAILED: doxygen check; begin output\n\n"
-  echo -e "$DOXYGEN"
-  DOXYGEN_RETVAL=1 #because return value is not generated by doxygen 1.8.20
-  echo -e "\n\n>>>> FAILED: doxygen check; end output\n\n"
-else
-  echo -e "\n\n>>>> PASSED: doxygen check\n\n"
-fi
-
 RETVALS=(
-  $CR_RETVAL $PRE_COMMIT_RETVAL $CLANG_FORMAT_RETVAL $DOXYGEN_RETVAL
+  $CR_RETVAL $PRE_COMMIT_RETVAL $CLANG_FORMAT_RETVAL $HEADER_META_RETVAL
 )
 IFS=$'\n'
 RETVAL=`echo "${RETVALS[*]}" | sort -nr | head -n1`

diff --git a/conda/environments/cudf_dev_cuda11.5.yml b/conda/environments/cudf_dev_cuda11.5.yml
@@ -43,6 +43,7 @@ dependencies:
   - black=22.3.0
   - isort=5.6.4
   - mypy=0.782
+  - doxygen=1.8.20
   - pydocstyle=6.1.1
   - typing_extensions
   - pre-commit

diff --git a/cpp/doxygen/Doxyfile b/cpp/doxygen/Doxyfile
@@ -1,4 +1,4 @@
-# Doxyfile 1.8.18
+# Doxyfile 1.8.20
 
 # This file describes the settings to be used by the documentation system
 # doxygen (www.doxygen.org) for a project.
@@ -93,14 +93,6 @@ ALLOW_UNICODE_NAMES    = NO
 
 OUTPUT_LANGUAGE        = English
 
-# The OUTPUT_TEXT_DIRECTION tag is used to specify the direction in which all
-# documentation generated by doxygen is written. Doxygen will use this
-# information to generate all generated output in the proper direction.
-# Possible values are: None, LTR, RTL and Context.
-# The default value is: None.
-
-OUTPUT_TEXT_DIRECTION  = None
-
 # If the BRIEF_MEMBER_DESC tag is set to YES, doxygen will include brief member
 # descriptions after the members that are listed in the file and class
 # documentation (similar to Javadoc). Set to NO to disable this.
@@ -217,6 +209,14 @@ QT_AUTOBRIEF           = NO
 
 MULTILINE_CPP_IS_BRIEF = NO
 
+# By default Python docstrings are displayed as preformatted text and doxygen's
+# special commands cannot be used. By setting PYTHON_DOCSTRING to NO the
+# doxygen's special commands can be used and the contents of the docstring
+# documentation blocks is shown as doxygen documentation.
+# The default value is: YES.
+
+PYTHON_DOCSTRING       = YES
+
 # If the INHERIT_DOCS tag is set to YES then an undocumented member inherits the
 # documentation from any documented member that it re-implements.
 # The default value is: YES.
@@ -440,6 +440,19 @@ TYPEDEF_HIDES_STRUCT   = NO
 
 LOOKUP_CACHE_SIZE      = 0
 
+# The NUM_PROC_THREADS specifies the number threads doxygen is allowed to use
+# during processing. When set to 0 doxygen will based this on the number of
+# cores available in the system. You can set it explicitly to a value larger
+# than 0 to get more control over the balance between CPU load and processing
+# speed. At this moment only the input processing can be done using multiple
+# threads. Since this is still an experimental feature the default is set to 1,
+# which efficively disables parallel processing. Please report any issues you
+# encounter. Generating dot graphs in parallel is controlled by the
+# DOT_NUM_THREADS setting.
+# Minimum value: 0, maximum value: 32, default value: 1.
+
+NUM_PROC_THREADS       = 1
+
 #---------------------------------------------------------------------------
 # Build related configuration options
 #---------------------------------------------------------------------------
@@ -544,7 +557,7 @@ INTERNAL_DOCS          = NO
 # names in lower-case letters. If set to YES, upper-case letters are also
 # allowed. This is useful if you have classes or files whose names only differ
 # in case and if your file system supports case sensitive file names. Windows
-# (including Cygwin) ands Mac users are advised to set this option to NO.
+# (including Cygwin) and Mac users are advised to set this option to NO.
 # The default value is: system dependent.
 
 CASE_SENSE_NAMES       = YES
@@ -820,10 +833,10 @@ INPUT                  = main_page.md \
                          ../include \
                          ../include/cudf_test/column_wrapper.hpp \
                          ../include/cudf_test/column_utilities.hpp \
-                          ../include/cudf_test/iterator_utilities.hpp \
-                          ../include/cudf_test/table_utilities.hpp \
-                          ../include/cudf_test/type_lists.hpp \
-                          ../include/cudf_test/type_list_utilities.hpp \
+                         ../include/cudf_test/iterator_utilities.hpp \
+                         ../include/cudf_test/table_utilities.hpp \
+                         ../include/cudf_test/type_lists.hpp \
+                         ../include/cudf_test/type_list_utilities.hpp \
                          ../libcudf_kafka/include
 
 # This tag can be used to specify the character encoding of the source files
@@ -887,7 +900,9 @@ EXCLUDE_SYMLINKS       = NO
 # Note that the wildcards are matched against the file with absolute path, so to
 # exclude all test directories for example use the pattern */test/*
 
-EXCLUDE_PATTERNS       = */nvtx/* */detail/* */cudf_test/*
+EXCLUDE_PATTERNS       = */nvtx/* \
+                         */detail/* \
+                         */cudf_test/*
 
 # The EXCLUDE_SYMBOLS tag can be used to specify one or more symbol names
 # (namespaces, classes, functions, etc.) that should be excluded from the
@@ -1081,13 +1096,6 @@ VERBATIM_HEADERS       = YES
 
 ALPHABETICAL_INDEX     = YES
 
-# The COLS_IN_ALPHA_INDEX tag can be used to specify the number of columns in
-# which the alphabetical index list will be split.
-# Minimum value: 1, maximum value: 20, default value: 5.
-# This tag requires that the tag ALPHABETICAL_INDEX is set to YES.
-
-COLS_IN_ALPHA_INDEX    = 5
-
 # In case all classes in a project start with a common prefix, all classes will
 # be put under the same header in the alphabetical index. The IGNORE_PREFIX tag
 # can be used to specify a prefix (or a list of prefixes) that should be ignored
@@ -1160,7 +1168,7 @@ HTML_FOOTER            =
 # obsolete.
 # This tag requires that the tag GENERATE_HTML is set to YES.
 
-HTML_STYLESHEET        = 
+HTML_STYLESHEET        =
 
 # The HTML_EXTRA_STYLESHEET tag can be used to specify additional user-defined
 # cascading style sheets that are included after the standard style sheets
@@ -1334,7 +1342,7 @@ CHM_FILE               =
 HHC_LOCATION           =
 
 # The GENERATE_CHI flag controls if a separate .chi index file is generated
-# (YES) or that it should be included in the master .chm file (NO).
+# (YES) or that it should be included in the main .chm file (NO).
 # The default value is: NO.
 # This tag requires that the tag GENERATE_HTMLHELP is set to YES.
 
@@ -1500,8 +1508,8 @@ EXT_LINKS_IN_WINDOW    = NO
 # tool (see https://github.com/dawbarton/pdf2svg) or inkscape (see
 # https://inkscape.org) to generate formulas as SVG images instead of PNGs for
 # the HTML output. These images will generally look nicer at scaled resolutions.
-# Possible values are: png The default and svg Looks nicer but requires the
-# pdf2svg tool.
+# Possible values are: png (the default) and svg (looks nicer but requires the
+# pdf2svg or inkscape tool).
 # The default value is: png.
 # This tag requires that the tag GENERATE_HTML is set to YES.
 
@@ -1801,9 +1809,11 @@ LATEX_EXTRA_FILES      =
 
 PDF_HYPERLINKS         = YES
 
-# If the USE_PDFLATEX tag is set to YES, doxygen will use pdflatex to generate
-# the PDF file directly from the LaTeX files. Set this option to YES, to get a
-# higher quality PDF documentation.
+# If the USE_PDFLATEX tag is set to YES, doxygen will use the engine as
+# specified with LATEX_CMD_NAME to generate the PDF file directly from the LaTeX
+# files. Set this option to YES, to get a higher quality PDF documentation.
+#
+# See also section LATEX_CMD_NAME for selecting the engine.
 # The default value is: YES.
 # This tag requires that the tag GENERATE_LATEX is set to YES.
 
@@ -1825,16 +1835,6 @@ LATEX_BATCHMODE        = NO
 
 LATEX_HIDE_INDICES     = NO
 
-# If the LATEX_SOURCE_CODE tag is set to YES then doxygen will include source
-# code with syntax highlighting in the LaTeX output.
-#
-# Note that which sources are shown also depends on other settings such as
-# SOURCE_BROWSER.
-# The default value is: NO.
-# This tag requires that the tag GENERATE_LATEX is set to YES.
-
-LATEX_SOURCE_CODE      = NO
-
 # The LATEX_BIB_STYLE tag can be used to specify the style to use for the
 # bibliography, e.g. plainnat, or ieeetr. See
 # https://en.wikipedia.org/wiki/BibTeX and \cite for more info.
@@ -1915,16 +1915,6 @@ RTF_STYLESHEET_FILE    =
 
 RTF_EXTENSIONS_FILE    =
 
-# If the RTF_SOURCE_CODE tag is set to YES then doxygen will include source code
-# with syntax highlighting in the RTF output.
-#
-# Note that which sources are shown also depends on other settings such as
-# SOURCE_BROWSER.
-# The default value is: NO.
-# This tag requires that the tag GENERATE_RTF is set to YES.
-
-RTF_SOURCE_CODE        = NO
-
 #---------------------------------------------------------------------------
 # Configuration options related to the man page output
 #---------------------------------------------------------------------------
@@ -2021,15 +2011,6 @@ GENERATE_DOCBOOK       = NO
 
 DOCBOOK_OUTPUT         = docbook
 
-# If the DOCBOOK_PROGRAMLISTING tag is set to YES, doxygen will include the
-# program listings (including syntax highlighting and cross-referencing
-# information) to the DOCBOOK output. Note that enabling this will significantly
-# increase the size of the DOCBOOK output.
-# The default value is: NO.
-# This tag requires that the tag GENERATE_DOCBOOK is set to YES.
-
-DOCBOOK_PROGRAMLISTING = NO
-
 #---------------------------------------------------------------------------
 # Configuration options for the AutoGen Definitions output
 #---------------------------------------------------------------------------
@@ -2137,9 +2118,9 @@ INCLUDE_FILE_PATTERNS  =
 # recursively expanded use the := operator instead of the = operator.
 # This tag requires that the tag ENABLE_PREPROCESSING is set to YES.
 
-PREDEFINED              = __device__= \
-                          __host__= \
-                          DOXYGEN_SHOULD_SKIP_THIS
+PREDEFINED             = __device__= \
+                         __host__= \
+                         DOXYGEN_SHOULD_SKIP_THIS
 
 # If the MACRO_EXPANSION and EXPAND_ONLY_PREDEF tags are set to YES then this
 # tag can be used to specify a list of macro names that should be expanded. The