Merge pull request #1415 from IntelPython/docs/config_options

[Documentation] config options

docs/_templates/autoapi/python/module.rst

@@ -1,8 +1,11 @@
 {% import 'macros.rst' as macros %}
 
 {% if not obj.display %}
+{% if not "config" in obj.name %}
+
 :orphan:
 
+{% endif %}
 {% endif %}
 {{ obj.name }}
 {{ "=" * obj.name|length }}
@@ -57,13 +60,14 @@ Submodules
 {% set visible_children = obj.children|selectattr("display")|rejectattr("imported")|list %}
 {% endif %}
 {% if visible_children %}
-Overview
---------
+
 
 {% set visible_classes = visible_children|selectattr("type", "equalto", "class")|list %}
 {% set visible_functions = visible_children|selectattr("type", "equalto", "function")|list %}
 {% set visible_attributes = visible_children|selectattr("type", "equalto", "data")|list %}
 {% if "show-module-summary" in autoapi_options and (visible_classes or visible_functions) %}
+Overview
+--------
 {% block classes scoped %}
 {% if visible_classes %}
 {{ macros.auto_summary(visible_classes, title="Classes") }}

docs/source/config_options.rst

@@ -0,0 +1,6 @@
+.. _configopts:
+
+Configuration Options
+#####################
+
+.. include:: ./autoapi/numba_dpex/core/config/index.rst

docs/source/index.rst

@@ -48,6 +48,7 @@ Data Parallel Extension for Numba*
    programming_model
    user_guide/index
    autoapi/index
+   config_options
    experimental/index
    useful_links
 

numba_dpex/core/config.py

@@ -2,8 +2,35 @@
 #
 # SPDX-License-Identifier: Apache-2.0
 
+"""
+The config options are meant to provide extra information and tweak optimization
+configurations to help debug code generation issues.
+
+There are two ways of setting these config options:
+
+- Config options can be directly set programmatically, *e.g.*,
+
+    .. code-block:: python
+
+        from numba_dpex.core.config import DUMP_KERNEL_LLVM
+
+        DUMP_KERNEL_LLVM = 1
+
+- The options can also be set globally using environment flags. The name of the
+  environment variable for every config option is annotated next to its
+  definition.
+
+    .. code-block:: bash
+
+        export NUMBA_DPEX_DUMP_KERNEL_LLVM = 1
+
+"""
+
+from __future__ import annotations
+
 import logging
 import os
+from typing import Annotated
 
 from numba.core import config
 
@@ -50,39 +77,98 @@ def __getattr__(name):
     return getattr(config, name)
 
 
-# To save intermediate files generated by th compiler
-SAVE_IR_FILES = _readenv("NUMBA_DPEX_SAVE_IR_FILES", int, 0)
-
-# Dump offload diagnostics
-OFFLOAD_DIAGNOSTICS = _readenv("NUMBA_DPEX_OFFLOAD_DIAGNOSTICS", int, 0)
-
-# Emit debug info
-DEBUG = _readenv("NUMBA_DPEX_DEBUG", int, config.DEBUG)
-# The default value for the `debug` flag
-DEBUGINFO_DEFAULT = _readenv(
-    "NUMBA_DPEX_DEBUGINFO", int, config.DEBUGINFO_DEFAULT
-)
-
-# Emit LLVM IR generated for kernel decorated function
-DUMP_KERNEL_LLVM = _readenv("NUMBA_DPEX_DUMP_KERNEL_LLVM", int, 0)
-
-# Emit LLVM module generated to launch a kernel decorated function
-DUMP_KERNEL_LAUNCHER = _readenv("NUMBA_DPEX_DUMP_KERNEL_LAUNCHER", int, 0)
-
-# Enables debug printf messages inside the kernel launcher module generated for
-# a kernel decorated function
-DEBUG_KERNEL_LAUNCHER = _readenv("NUMBA_DPEX_DEBUG_KERNEL_LAUNCHER", int, 0)
-
-# Sets build kernel options for the kernel compilation on the device side.
-# For available OpenCL options refer
-# https://intel.github.io/llvm-docs/clang/ClangCommandLineReference.html#opencl-options
-BUILD_KERNEL_OPTIONS = _readenv("NUMBA_DPEX_BUILD_KERNEL_OPTIONS", str, "")
+SAVE_IR_FILES: Annotated[
+    int,
+    "Save the IR files (LLVM and SPIRV-V) generated for each kernel to"
+    " current directory",
+    "default = 0",
+    "ENVIRONMENT FLAG: NUMBA_DPEX_SAVE_IR_FILES",
+] = _readenv("NUMBA_DPEX_SAVE_IR_FILES", int, 0)
+
+OFFLOAD_DIAGNOSTICS: Annotated[
+    int,
+    "Print diagnostic information for automatic offloading of parfor nodes "
+    "to kernels",
+    "default = 0",
+    "ENVIRONMENT FLAG: NUMBA_DPEX_OFFLOAD_DIAGNOSTICS",
+] = _readenv("NUMBA_DPEX_OFFLOAD_DIAGNOSTICS", int, 0)
+
+DEBUG: Annotated[
+    int,
+    "Generates extra debug prints when set to a non-zero value",
+    "default = 0",
+    "ENVIRONMENT FLAG: NUMBA_DPEX_DEBUG",
+] = _readenv("NUMBA_DPEX_DEBUG", int, config.DEBUG)
+
+DEBUGINFO_DEFAULT: Annotated[
+    int,
+    "Compiles in the debug mode generating debug symbols in the compiler IR. "
+    'It is a global way of setting the "debug" keyword for all '
+    "numba_dpex.kernel and numba_dpex.device_func decorators "
+    "used in a program.",
+    "default = 0",
+    "ENVIRONMENT FLAG: NUMBA_DPEX_DEBUGINFO",
+] = _readenv("NUMBA_DPEX_DEBUGINFO", int, config.DEBUGINFO_DEFAULT)
+
+DUMP_KERNEL_LLVM: Annotated[
+    int,
+    "Writes the optimized LLVM IR generated for a "
+    "numba_dpex.kernel decorated function to current directory",
+    "default = 0",
+    "ENVIRONMENT FLAG: NUMBA_DPEX_DUMP_KERNEL_LLVM",
+] = _readenv("NUMBA_DPEX_DUMP_KERNEL_LLVM", int, 0)
+
+DUMP_KERNEL_LAUNCHER: Annotated[
+    int,
+    "Writes the optimized LLVM IR generated for every "
+    "numba_dpex.call_kernel function to current directory",
+    "default = 0",
+    "ENVIRONMENT FLAG: NUMBA_DPEX_DUMP_KERNEL_LAUNCHER",
+] = _readenv("NUMBA_DPEX_DUMP_KERNEL_LAUNCHER", int, 0)
+
+DEBUG_KERNEL_LAUNCHER: Annotated[
+    int,
+    "Enables debug printf messages inside the compiled module generated for a "
+    "numba_dpex.call_kernel function."
+    "default = 0",
+    "ENVIRONMENT FLAG: NUMBA_DPEX_DEBUG_KERNEL_LAUNCHER",
+] = _readenv("NUMBA_DPEX_DEBUG_KERNEL_LAUNCHER", int, 0)
+
+BUILD_KERNEL_OPTIONS: Annotated[
+    str,
+    "Can use used to pass extra flags to the device driver compiler during "
+    "kernel compilation. For available OpenCL options refer "
+    "https://intel.github.io/llvm-docs/clang/ClangCommandLineReference.html#opencl-options",
+    'default = ""',
+    "ENVIRONMENT FLAG: NUMBA_DPEX_BUILD_KERNEL_OPTIONS",
+] = _readenv("NUMBA_DPEX_BUILD_KERNEL_OPTIONS", str, "")
 
 TESTING_SKIP_NO_DEBUGGING = _readenv(
     "NUMBA_DPEX_TESTING_SKIP_NO_DEBUGGING", int, 1
 )
-TESTING_LOG_DEBUGGING = _readenv("NUMBA_DPEX_TESTING_LOG_DEBUGGING", int, DEBUG)
-
-DPEX_OPT = _readenv("NUMBA_DPEX_OPT", int, 2)
 
-INLINE_THRESHOLD = _readenv("NUMBA_DPEX_INLINE_THRESHOLD", int, 2)
+TESTING_LOG_DEBUGGING: Annotated[
+    int,
+    "Generates extra logs when using gdb to debug a kernel",
+    "defaults = 0",
+    "ENVIRONMENT_FLAG: NUMBA_DPEX_TESTING_LOG_DEBUGGING",
+] = _readenv("NUMBA_DPEX_TESTING_LOG_DEBUGGING", int, DEBUG)
+
+DPEX_OPT: Annotated[
+    int,
+    "Sets the optimization level globally for every function "
+    "compiled by numba-dpex",
+    "default = 2",
+    "ENVIRONMENT_FLAG: NUMBA_DPEX_OPT",
+] = _readenv("NUMBA_DPEX_OPT", int, 2)
+
+INLINE_THRESHOLD: Annotated[
+    int,
+    "Sets the inlining-threshold level globally for every function "
+    "compiled by numba-dpex. A higher value enables more aggressive inlining "
+    "settings for the compiler. Note: Even if NUMBA_DPEX_INLINE_THRESHOLD is "
+    'set to 0, many internal functions that are attributed "alwaysinline" '
+    "will still get inlined.",
+    "default = 2",
+    "ENVIRONMENT_FLAG: NUMBA_DPEX_INLINE_THRESHOLD",
+] = _readenv("NUMBA_DPEX_INLINE_THRESHOLD", int, 2)