diff --git a/CLAUDE.md b/CLAUDE.md index ef8d92f..d73a716 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -39,6 +39,19 @@ coverage report coverage html && open htmlcov/index.html ``` +### Documentation + +```bash +# Build HTML documentation +make -C docs html + +# Live-reload documentation server +make -C docs serve + +# Remove build artifacts +make -C clean +``` + ### Linting and Pre-commit ```bash diff --git a/dependencies.yaml b/dependencies.yaml index 63e2900..afc80b5 100644 --- a/dependencies.yaml +++ b/dependencies.yaml @@ -75,6 +75,15 @@ dependencies: - output_types: [pyproject, requirements] packages: - importlib-metadata >= 4.13.0; python_version < '3.12' + docs: + common: + - output_types: [conda, requirements, pyproject] + packages: + - pydata-sphinx-theme>=0.16.1 + - sphinx>=8 + - sphinx-autobuild>=2025.8.25 + - sphinx-copybutton>=0.5.2 + - sphinx-llm>=0.3.0 test_python: common: - output_types: [conda, requirements, pyproject] diff --git a/docs/Makefile b/docs/Makefile index d0c3cbf..5e3fc1c 100644 --- a/docs/Makefile +++ b/docs/Makefile @@ -12,7 +12,10 @@ BUILDDIR = build help: @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) -.PHONY: help Makefile +.PHONY: help serve Makefile + +serve: + sphinx-autobuild "$(SOURCEDIR)" "$(BUILDDIR)/html" $(SPHINXOPTS) $(O) # Catch-all target: route all unknown targets to Sphinx using the new # "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). diff --git a/docs/source/api/checks.rst b/docs/source/api/checks.rst new file mode 100644 index 0000000..363e26f --- /dev/null +++ b/docs/source/api/checks.rst @@ -0,0 +1,42 @@ +.. SPDX-FileCopyrightText: Copyright (c) 2025-2026, NVIDIA CORPORATION & AFFILIATES. All rights reserved. +.. SPDX-License-Identifier: Apache-2.0 + +Health Checks +============= + +Built-in health check modules registered via the ``rapids_doctor_check`` +entry point group in ``pyproject.toml``. + +All check functions follow the contract described in :doc:`../plugin_development`. + +GPU Checks +---------- + +.. automodule:: rapids_cli.doctor.checks.gpu + :members: + :undoc-members: + :show-inheritance: + +CUDA Driver Checks +------------------ + +.. automodule:: rapids_cli.doctor.checks.cuda_driver + :members: + :undoc-members: + :show-inheritance: + +Memory Checks +------------- + +.. automodule:: rapids_cli.doctor.checks.memory + :members: + :undoc-members: + :show-inheritance: + +NVLink Checks +------------- + +.. automodule:: rapids_cli.doctor.checks.nvlink + :members: + :undoc-members: + :show-inheritance: diff --git a/docs/source/api/cli.rst b/docs/source/api/cli.rst new file mode 100644 index 0000000..1580d51 --- /dev/null +++ b/docs/source/api/cli.rst @@ -0,0 +1,16 @@ +.. SPDX-FileCopyrightText: Copyright (c) 2025-2026, NVIDIA CORPORATION & AFFILIATES. All rights reserved. +.. SPDX-License-Identifier: Apache-2.0 + +CLI Module +========== + +The ``rapids_cli.cli`` module defines the main CLI entry point and subcommands +using `rich-click `_. + +The CLI is registered as a console script called ``rapids`` via the +``[project.scripts]`` entry in ``pyproject.toml``. + +.. automodule:: rapids_cli.cli + :members: + :undoc-members: + :show-inheritance: diff --git a/docs/source/api/debug.rst b/docs/source/api/debug.rst new file mode 100644 index 0000000..aa4e84b --- /dev/null +++ b/docs/source/api/debug.rst @@ -0,0 +1,33 @@ +.. SPDX-FileCopyrightText: Copyright (c) 2025-2026, NVIDIA CORPORATION & AFFILIATES. All rights reserved. +.. SPDX-License-Identifier: Apache-2.0 + +Debug Module +============ + +The ``rapids_cli.debug.debug`` module gathers system and environment information +for troubleshooting RAPIDS installations. + +:func:`~rapids_cli.debug.debug.run_debug` is the main entry point. It collects: + +- Platform and OS details (from ``platform`` and ``/etc/os-release``) +- NVIDIA driver and CUDA versions (via ``pynvml``) +- CUDA runtime path (via ``cuda-pathfinder``) +- System CUDA toolkit locations (globbing ``/usr/local/cuda*``) +- Python version and hash info +- All installed package versions +- pip freeze and conda list output +- Tool versions: pip, conda, uv, pixi, g++, cmake, nvcc + +Output is either a Rich-formatted console table or JSON (``--json``). + +Example: + +``rapids debug --json > ".json"`` + +API +--- + +.. automodule:: rapids_cli.debug.debug + :members: + :undoc-members: + :show-inheritance: diff --git a/docs/source/api/doctor.rst b/docs/source/api/doctor.rst new file mode 100644 index 0000000..5cfcd32 --- /dev/null +++ b/docs/source/api/doctor.rst @@ -0,0 +1,48 @@ +.. SPDX-FileCopyrightText: Copyright (c) 2025-2026, NVIDIA CORPORATION & AFFILIATES. All rights reserved. +.. SPDX-License-Identifier: Apache-2.0 + +Doctor Module +============= + +The ``rapids_cli.doctor.doctor`` module orchestrates health check discovery +and execution. + +The CUDA + Python software stack spans multiple layers — the GPU driver, the +CUDA runtime, C/C++ libraries, and Python packages — each managed by different +package managers (OS packages, CUDA toolkit installers, conda, pip). Because no +single package manager owns the full stack, misconfigurations across layer +boundaries are common and difficult to diagnose. ``rapids doctor`` validates +compatibility across these layers, from the driver through CUDA to the Python +libraries, and provides actionable feedback when an incompatibility is found. + +Health checks are bundled with the RAPIDS libraries you install rather than +hard-coded into ``rapids-cli`` itself. When you install a library such as +cuDF or cuML, any checks it ships are automatically available to +``rapids doctor`` — no extra configuration required. + +You can run all discovered checks at once, or filter to a specific library +by passing its name as an argument: + +.. code-block:: bash + + # Run every available check + rapids doctor + + # Run only checks related to cudf + rapids doctor cudf + + # See which checks would run without executing them + rapids doctor --dry-run --verbose + +Results are collected into :class:`~rapids_cli.doctor.doctor.CheckResult` +objects that track pass/fail status, return values, errors, and warnings. +For details on how checks are discovered and executed, or how to write your +own, see :doc:`/plugin_development`. + +API +--- + +.. automodule:: rapids_cli.doctor.doctor + :members: + :undoc-members: + :show-inheritance: diff --git a/docs/source/conf.py b/docs/source/conf.py index 3b59adc..984a537 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -1,44 +1,82 @@ -# SPDX-FileCopyrightText: Copyright (c) 2025, NVIDIA CORPORATION & AFFILIATES. -# All rights reserved. +# SPDX-FileCopyrightText: Copyright (c) 2025-2026, NVIDIA CORPORATION & AFFILIATES. All rights reserved. # SPDX-License-Identifier: Apache-2.0 # Configuration file for the Sphinx documentation builder. # # For the full list of built-in configuration values, see the documentation: # https://www.sphinx-doc.org/en/master/usage/configuration.html -# -- Project information ----------------------------------------------------- -# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information - - +import datetime import os import sys -sys.path.insert(0, os.path.abspath("../rapids_cli")) +sys.path.insert(0, os.path.abspath("../../")) +# -- Project information ----------------------------------------------------- project = "RAPIDS CLI" -copyright = "2024, NVIDIA RAPIDS" -author = "NVIDIA RAPIDS" -release = "2024" +html_title = "RAPIDS CLI" +copyright = f"{datetime.date.today().year}, NVIDIA" +author = "NVIDIA" # -- General configuration --------------------------------------------------- -# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration -extensions = [] +extensions = [ + "sphinx.ext.autodoc", + "sphinx.ext.viewcode", + "sphinx.ext.napoleon", + "sphinx.ext.intersphinx", + "sphinx_copybutton", + "sphinx_llm.txt", +] templates_path = ["_templates"] exclude_patterns = [] +copybutton_prompt_text = r">>> |\.\.\. |\$ |In \[\d*\]: | {2,5}\.\.\.: | {5,8}: " +copybutton_prompt_is_regexp = True + +# Napoleon settings for Google-style docstrings +napoleon_google_docstring = True +napoleon_numpy_docstring = False + +# Autodoc settings +autodoc_default_options = { + "members": True, + "member-order": "bysource", + "undoc-members": True, +} + +intersphinx_mapping = { + "python": ("https://docs.python.org/3", None), +} # -- Options for HTML output ------------------------------------------------- -# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output -html_theme = "alabaster" +html_theme = "pydata_sphinx_theme" + +html_theme_options = { + "header_links_before_dropdown": 7, + "icon_links": [], + "logo": { + "link": "https://docs.rapids.ai/", + }, + "github_url": "https://github.com/rapidsai/rapids-cli", + "show_toc_level": 1, + "navbar_align": "right", +} + +html_sidebars = { + "**": ["sidebar-nav-bs", "sidebar-ethical-ads"], +} + html_static_path = ["_static"] -extensions = [ - "sphinx.ext.autodoc", - "sphinx.ext.autosummary", - "sphinx.ext.viewcode", - "sphinx.ext.napoleon", # For Google and NumPy style docstrings -] + +def setup(app): + app.add_css_file("https://docs.rapids.ai/assets/css/custom.css") + app.add_css_file( + "https://cdnjs.cloudflare.com/ajax/libs/font-awesome/5.9.0/css/all.min.css" + ) + app.add_js_file( + "https://docs.rapids.ai/assets/js/custom.js", loading_method="defer" + ) diff --git a/docs/source/cuda_driver.rst b/docs/source/cuda_driver.rst deleted file mode 100644 index a4d69d6..0000000 --- a/docs/source/cuda_driver.rst +++ /dev/null @@ -1,35 +0,0 @@ -.. _cuda_driver: - -CUDA Driver Checks -================== - -This module provides functions to check the availability of CUDA, retrieve CUDA version, -and verify compatibility between the CUDA toolkit and NVIDIA drivers. - -Functions ---------- -.. autofunction:: rapids_cli.doctor.checks.cuda_driver.cuda_check - - Checks if CUDA is available on the system by initializing the NVML and retrieving the CUDA driver version. - - :return: True if CUDA is available, False otherwise. - -.. autofunction:: rapids_cli.doctor.checks.cuda_driver.get_cuda_version - - Retrieves the version of the installed CUDA toolkit. - - :return: A string representing the CUDA version or None if CUDA is not found. - -.. autofunction:: rapids_cli.doctor.checks.cuda_driver.get_driver_version - - Retrieves the installed NVIDIA driver version. - - :return: A string representing the NVIDIA driver version or None if the driver is not found. - -.. autofunction:: rapids_cli.doctor.checks.cuda_driver.check_driver_compatibility - - Checks the compatibility between the installed CUDA version and the NVIDIA driver version. - - This function prints whether the installed versions are compatible with RAPIDS. - - :return: None diff --git a/docs/source/doctor.rst b/docs/source/doctor.rst deleted file mode 100644 index 33be8d8..0000000 --- a/docs/source/doctor.rst +++ /dev/null @@ -1,19 +0,0 @@ -.. _doctor: - -Doctor -========= - -Overview of Doctor. - -.. automodule:: doctor - :members: - :undoc-members: - :show-inheritance: - -Submodules ----------- - -.. automodule:: doctor.checks - :members: - :undoc-members: - :show-inheritance: diff --git a/docs/source/index.rst b/docs/source/index.rst index 94df6bc..474bf39 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -1,26 +1,51 @@ -.. RAPIDS CLI documentation master file, created by - sphinx-quickstart on Fri Oct 25 10:50:48 2024. - You can adapt this file completely to your liking, but it should at least - contain the root `toctree` directive. +.. SPDX-FileCopyrightText: Copyright (c) 2025-2026, NVIDIA CORPORATION & AFFILIATES. All rights reserved. +.. SPDX-License-Identifier: Apache-2.0 -RAPIDS CLI documentation +RAPIDS CLI Documentation ======================== -Add your content using ``reStructuredText`` syntax. See the -`reStructuredText `_ -documentation for details. +The RAPIDS CLI is a command-line tool for performing common RAPIDS operations, +primarily focused on health checks (``rapids doctor``) and debugging (``rapids debug``). +It uses a plugin system that allows RAPIDS libraries to register their own health checks +via Python entry points. +Quick Start +----------- + +.. code-block:: bash + + pip install rapids-cli + + # Run health checks + rapids doctor + + # Gather system info for debugging + rapids debug --json .. toctree:: :maxdepth: 2 - :caption: Contents: + :caption: User Guide + + user_guide + troubleshooting - doctor - cuda_driver +.. toctree:: + :maxdepth: 2 + :caption: Developer Guide + + plugin_development + +.. toctree:: + :maxdepth: 2 + :caption: API Reference + api/cli + api/doctor + api/debug + api/checks Indices and tables -=================== +================== * :ref:`genindex` * :ref:`modindex` diff --git a/docs/source/plugin_development.rst b/docs/source/plugin_development.rst new file mode 100644 index 0000000..d5b5e45 --- /dev/null +++ b/docs/source/plugin_development.rst @@ -0,0 +1,195 @@ +.. SPDX-FileCopyrightText: Copyright (c) 2025-2026, NVIDIA CORPORATION & AFFILIATES. All rights reserved. +.. SPDX-License-Identifier: Apache-2.0 + +Plugin Development +================== + +Any package can add checks to ``rapids doctor`` by exposing a function via a +Python entry point in the ``rapids_doctor_check`` group. + +Quick Start +----------- + +1. Create a check function: + + .. code-block:: python + + # my_package/health_checks.py + + + def my_check(verbose=False, **kwargs): + """Check that my_package is working correctly.""" + try: + import my_package + except ImportError as e: + raise ImportError( + "my_package not found. Install with: pip install my_package" + ) from e + + if verbose: + return f"my_package {my_package.__version__} is available" + +2. Register it in ``pyproject.toml``: + + .. code-block:: toml + + [project.entry-points.rapids_doctor_check] + my_check = "my_package.health_checks:my_check" + +3. Install and verify: + + .. code-block:: bash + + pip install -e . + rapids doctor --verbose --dry-run + +Check Execution Flow +-------------------- + +When ``rapids doctor`` runs, checks go through four stages: + +1. **Discovery**: Scan ``rapids_doctor_check`` entry points and load check + functions. ``ImportError`` and ``AttributeError`` during loading are + silently suppressed via ``contextlib.suppress``. + +2. **Filtering**: If filter arguments are provided, only checks whose + ``ep.value`` contains a filter substring are kept. + +3. **Execution**: Each check runs inside ``warnings.catch_warnings(record=True)`` + so warnings are captured. Exceptions are caught and stored rather than + propagated. + +4. **Reporting**: Warnings are printed, verbose output is shown for passing + checks, and failed checks are listed with their error messages. + +Check Function Contract +----------------------- + +Signature +^^^^^^^^^ + +.. code-block:: python + + def my_check(verbose=False, **kwargs): + """First line of docstring is shown in output.""" + ... + +- Accept ``verbose`` (bool) and ``**kwargs`` for forward compatibility. +- The first line of the docstring is used as the check description in output. +- New keyword arguments may be added in the future but will never be removed, + so ``**kwargs`` ensures your check won't break. + +Return Values +^^^^^^^^^^^^^ + +- **Pass**: Return any value. Returning a string provides extra info shown in + ``--verbose`` mode. +- **Fail**: Raise an exception. The message should tell the user how to fix it. +- **Warn**: Call ``warnings.warn("message", stacklevel=2)`` for non-fatal issues. + Warnings are captured and displayed but do not cause the check to fail. + +Examples +-------- + +GPU memory requirement check: + +.. code-block:: python + + import pynvml + + + def gpu_memory_check(verbose=False, **kwargs): + """Check that GPU has at least 8GB memory.""" + pynvml.nvmlInit() + handle = pynvml.nvmlDeviceGetHandleByIndex(0) + mem = pynvml.nvmlDeviceGetMemoryInfo(handle) + available_gb = mem.total / (1024**3) + + if available_gb < 8: + raise ValueError( + f"Insufficient GPU memory: {available_gb:.1f}GB available, 8GB required" + ) + + if verbose: + return f"GPU memory: {available_gb:.1f}GB" + +Non-fatal warning: + +.. code-block:: python + + import warnings + + + def config_check(verbose=False, **kwargs): + """Check optional configuration.""" + if not optimal_condition(): + warnings.warn( + "Suboptimal configuration detected. Performance may be degraded.", + stacklevel=2, + ) + +Multiple checks from one package: + +.. code-block:: toml + + [project.entry-points.rapids_doctor_check] + my_pkg_import = "my_package.checks:import_check" + my_pkg_gpu = "my_package.checks:gpu_check" + my_pkg_functional = "my_package.checks:functional_check" + +Testing Your Plugin +------------------- + +Verify discovery: + +.. code-block:: bash + + rapids doctor --verbose --dry-run | grep my_check + +Run only your checks: + +.. code-block:: bash + + rapids doctor --verbose my_package + +Unit test with mocks (following the pattern in ``rapids_cli/tests/``): + +.. code-block:: python + + from unittest.mock import patch + + import pytest + + from my_package.health_checks import my_check + + + def test_my_check_success(): + result = my_check(verbose=True) + assert result is not None + + + def test_my_check_failure(): + with pytest.raises(ValueError, match="expected error"): + my_check(verbose=False) + +Troubleshooting +--------------- + +**Check not discovered**: Verify the entry point name is in the output of: + +.. code-block:: bash + + python -c "from importlib.metadata import entry_points; \ + print([ep.name for ep in entry_points(group='rapids_doctor_check')])" + +If missing, reinstall with ``pip install -e . --force-reinstall --no-deps``. + +**Import errors are silent**: The doctor module uses ``contextlib.suppress`` +to skip checks that fail to import. Test your import directly: + +.. code-block:: bash + + python -c "from my_package.health_checks import my_check" + +See the built-in checks in ``rapids_cli/doctor/checks/`` for reference +implementations. diff --git a/docs/source/troubleshooting.rst b/docs/source/troubleshooting.rst new file mode 100644 index 0000000..5da7f2c --- /dev/null +++ b/docs/source/troubleshooting.rst @@ -0,0 +1,112 @@ +.. SPDX-FileCopyrightText: Copyright (c) 2025-2026, NVIDIA CORPORATION & AFFILIATES. All rights reserved. +.. SPDX-License-Identifier: Apache-2.0 + +Troubleshooting +=============== + +No GPUs Detected +---------------- + +``rapids doctor`` reports "No available GPUs detected". + +1. Verify NVIDIA drivers are installed: + + .. code-block:: bash + + nvidia-smi + +2. Check that GPU is visible from Python: + + .. code-block:: bash + + python -c "import pynvml; pynvml.nvmlInit(); print(pynvml.nvmlDeviceGetCount())" + +3. If running in a container, ensure GPU passthrough is enabled: + + .. code-block:: bash + + docker run --gpus all ... + +Insufficient Compute Capability +-------------------------------- + +"GPU requires compute capability 7 or higher". + +RAPIDS requires Volta-generation GPUs or newer (compute capability 7.0+). +Supported GPUs include V100, A100, H100, and RTX 20xx/30xx/40xx series. +See https://developer.nvidia.com/cuda-gpus for a full list. + +CUDA Version Issues +------------------- + +"Unable to look up CUDA version". + +1. Check your CUDA driver version: + + .. code-block:: bash + + nvidia-smi | grep "CUDA Version" + +2. Ensure RAPIDS packages match your CUDA version: + + .. code-block:: bash + + # For CUDA 12.x + pip install cudf-cu12 + + # For CUDA 11.x + pip install cudf-cu11 + +Low Memory Warning +------------------ + +"System Memory to total GPU Memory ratio not at least 2:1 ratio." + +This is a warning, not a failure. RAPIDS recommends system RAM be at least +twice total GPU memory for optimal performance, particularly with Dask. +RAPIDS will still function with a lower ratio. + +Custom Checks Not Discovered +----------------------------- + +If ``rapids doctor --verbose`` doesn't show your custom check: + +1. Verify the entry point is registered: + + .. code-block:: bash + + python -c "from importlib.metadata import entry_points; \ + print([ep.name for ep in entry_points(group='rapids_doctor_check')])" + +2. Reinstall the package that provides the check: + + .. code-block:: bash + + pip install -e . --force-reinstall --no-deps + +3. Check for import errors by importing the check function directly: + + .. code-block:: bash + + python -c "from my_package.checks import my_check" + + Import errors during discovery are silently suppressed + (see ``contextlib.suppress`` in ``doctor.py``). + +General Debugging Steps +----------------------- + +1. Run with verbose output: + + .. code-block:: bash + + rapids doctor --verbose + +2. Gather full environment information: + + .. code-block:: bash + + rapids debug --json > debug_info.json + +3. Report issues at https://github.com/rapidsai/rapids-cli/issues with the + debug output attached. diff --git a/docs/source/user_guide.rst b/docs/source/user_guide.rst new file mode 100644 index 0000000..8656999 --- /dev/null +++ b/docs/source/user_guide.rst @@ -0,0 +1,121 @@ +.. SPDX-FileCopyrightText: Copyright (c) 2025-2026, NVIDIA CORPORATION & AFFILIATES. All rights reserved. +.. SPDX-License-Identifier: Apache-2.0 + +User Guide +========== + +The RAPIDS CLI provides two commands: ``rapids doctor`` for health checks and +``rapids debug`` for gathering system information. + +rapids doctor +------------- + +The ``doctor`` command performs health checks to ensure your RAPIDS environment +is properly configured. + +.. code-block:: bash + + rapids doctor + +Built-in checks verify: + +- GPU availability and compute capability (7.0+) +- CUDA driver version +- System memory to GPU memory ratio (recommends 2:1 for Dask) +- NVLink status (multi-GPU systems) + +Any installed RAPIDS library can register additional checks via the plugin system +(see :doc:`plugin_development`). + +Verbose Output +^^^^^^^^^^^^^^ + +The ``--verbose`` flag shows check discovery details and per-check output: + +.. code-block:: bash + + $ rapids doctor --verbose + Discovering checks + Found check 'gpu' provided by 'rapids_cli.doctor.checks.gpu:gpu_check' + ... + Discovered 5 checks + Running checks + gpu_check: GPU(s) detected: 2 + All checks passed! + +Dry Run +^^^^^^^ + +The ``--dry-run`` flag discovers checks without executing them, useful for +verifying plugin registration: + +.. code-block:: bash + + rapids doctor --dry-run + +Filtering +^^^^^^^^^ + +Pass filter arguments to run only matching checks. Filters match against +the check's module path: + +.. code-block:: bash + + # Run only cuDF-related checks + rapids doctor cudf + + # Run checks from multiple packages + rapids doctor cudf cuml + +Exit Codes +^^^^^^^^^^ + +- ``0``: All checks passed +- ``1``: One or more checks failed + +This makes ``rapids doctor`` suitable for scripting: + +.. code-block:: bash + + rapids doctor || exit 1 + +rapids debug +------------ + +The ``debug`` command gathers comprehensive system information for troubleshooting. + +.. code-block:: bash + + rapids debug + +Output includes: platform, NVIDIA driver version, CUDA version, CUDA runtime +path, system CTK locations, Python version, all installed package versions, +pip/conda package lists, available tools (pip, conda, uv, pixi, g++, cmake, +nvcc), and OS information. + +JSON Output +^^^^^^^^^^^ + +The ``--json`` flag produces machine-readable output: + +.. code-block:: bash + + rapids debug --json > debug_info.json + +This is useful for attaching to bug reports or comparing environments. + +CI/CD Integration +----------------- + +Example GitHub Actions usage: + +.. code-block:: yaml + + - name: Verify RAPIDS Environment + run: | + pip install rapids-cli + rapids doctor --verbose || exit 1 + + - name: Save Debug Info on Failure + if: failure() + run: rapids debug --json > debug.json diff --git a/rapids_cli/doctor/doctor.py b/rapids_cli/doctor/doctor.py index 0fdff86..e7cd0ad 100644 --- a/rapids_cli/doctor/doctor.py +++ b/rapids_cli/doctor/doctor.py @@ -34,26 +34,24 @@ def doctor_check( If specific subcommands are given, it validates them against valid subcommands and executes corresponding checks. - Parameters: - ---------- - filters : list (optional) - A list of filters to run specific checks. - - Raises: - ------- - ValueError: - If an invalid subcommand is provided. - - Notes: - ----- - The function discovers and loads check functions defined in entry points - under the 'rapids_doctor_check' group. It also checks specific - configurations related to a corresponding subcommand if given. + Args: + verbose: Whether to print verbose output. + dry_run: Whether to skip running checks. + filters: A list of filters to run specific checks containing specified + strings. For example, passing ``['cudf', 'cuml']`` will only run + checks containing those strings. + + Returns: + True if all checks passed (or dry_run is True), False otherwise. + + Note: + The function discovers and loads check functions defined in entry points + under the ``rapids_doctor_check`` group. It also checks specific + configurations related to a corresponding subcommand if given. Example: - -------- - > doctor_check([]) # Run all health checks - > doctor_check(['cudf']) # Run 'cudf' specific checks + >>> doctor_check(verbose=False, dry_run=False) + >>> doctor_check(verbose=False, dry_run=False, filters=['cudf']) """ filters = [] if not filters else filters console.print( diff --git a/rapids_cli/tests/test_doctor.py b/rapids_cli/tests/test_doctor.py index 7b9eb89..674b17d 100644 --- a/rapids_cli/tests/test_doctor.py +++ b/rapids_cli/tests/test_doctor.py @@ -100,15 +100,22 @@ def test_doctor_check_dry_run(capsys): def test_doctor_check_with_filters(capsys): """Test doctor_check with filters.""" + cudf_check = MagicMock( + side_effect=mock_passing_check, __name__="cudf_check", __doc__="cudf check." + ) + cuml_check = MagicMock( + side_effect=mock_passing_check, __name__="cuml_check", __doc__="cuml check." + ) + mock_ep1 = MagicMock() mock_ep1.name = "cudf_check" mock_ep1.value = "cudf.module:check" - mock_ep1.load.return_value = mock_passing_check + mock_ep1.load.return_value = cudf_check mock_ep2 = MagicMock() mock_ep2.name = "cuml_check" mock_ep2.value = "cuml.module:check" - mock_ep2.load.return_value = mock_passing_check + mock_ep2.load.return_value = cuml_check with patch( "rapids_cli.doctor.doctor.entry_points", return_value=[mock_ep1, mock_ep2] @@ -116,6 +123,9 @@ def test_doctor_check_with_filters(capsys): result = doctor_check(verbose=False, dry_run=False, filters=["cudf"]) assert result is True + cudf_check.assert_called_once() + cuml_check.assert_not_called() + def test_doctor_check_with_warnings(capsys): """Test doctor_check with checks that issue warnings."""