diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml index 46d5223f7d3..aad849de992 100644 --- 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 index db8a8d88b99..c6ab9f95088 100644 --- 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 new file mode 100755 index 00000000000..f260fbcd1a4 --- /dev/null +++ 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 index 0e8f33aa6d6..b0f91fb8c9a 100755 --- 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 index b2e77f9c9fb..93a20a90b18 100644 --- 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 index a0a0377aed0..f42e0158c06 100644 --- 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