Use PyData docs theme, reorganize C++ docs (#2137)

This is split off of #2087.

I am overhauling the RMM documentation. This is the first set of changes, which includes a new theme and a reorganization of the C++ docs. All docs now use Markdown / Myst.

The next phases will include docstring tweaks to fix various formatting/cross-linking issues (see #2138 and #2139 for current progress on this), an expansion of the Python API docs, and adding user guides for various features.

Authors:
  - Bradley Dice (https://github.com/bdice)

Approvers:
  - Matthew Murray (https://github.com/Matt711)
  - Rong Ou (https://github.com/rongou)
  - Jake Awe (https://github.com/AyodeAwe)

URL: #2137

Author: bdice

.gitignore

@@ -95,6 +95,7 @@ thirdparty/googletest/
 
 ## Documentation
 cpp/doxygen/html
+cpp/doxygen/latex
 cpp/doxygen/xml
 docs/_build
 

conda/environments/all_cuda-129_arch-aarch64.yaml

@@ -22,6 +22,7 @@ dependencies:
 - identify>=2.5.20
 - ipython
 - make
+- myst-parser
 - nbsphinx
 - ninja
 - numba-cuda>=0.19.1,<0.20.0a0
@@ -30,6 +31,7 @@ dependencies:
 - numpydoc
 - packaging
 - pre-commit
+- pydata-sphinx-theme>=0.15.4
 - pytest-cov
 - pytest<9.0.0a0
 - python>=3.10,<3.14
@@ -39,6 +41,6 @@ dependencies:
 - sphinx
 - sphinx-copybutton
 - sphinx-markdown-tables
-- sphinx_rtd_theme
+- sphinxcontrib-jquery
 - sysroot_linux-aarch64==2.28
 name: all_cuda-129_arch-aarch64

conda/environments/all_cuda-129_arch-x86_64.yaml

@@ -22,6 +22,7 @@ dependencies:
 - identify>=2.5.20
 - ipython
 - make
+- myst-parser
 - nbsphinx
 - ninja
 - numba-cuda>=0.19.1,<0.20.0a0
@@ -30,6 +31,7 @@ dependencies:
 - numpydoc
 - packaging
 - pre-commit
+- pydata-sphinx-theme>=0.15.4
 - pytest-cov
 - pytest<9.0.0a0
 - python>=3.10,<3.14
@@ -39,6 +41,6 @@ dependencies:
 - sphinx
 - sphinx-copybutton
 - sphinx-markdown-tables
-- sphinx_rtd_theme
+- sphinxcontrib-jquery
 - sysroot_linux-64==2.28
 name: all_cuda-129_arch-x86_64

conda/environments/all_cuda-130_arch-aarch64.yaml

@@ -22,6 +22,7 @@ dependencies:
 - identify>=2.5.20
 - ipython
 - make
+- myst-parser
 - nbsphinx
 - ninja
 - numba-cuda>=0.19.1,<0.20.0a0
@@ -30,6 +31,7 @@ dependencies:
 - numpydoc
 - packaging
 - pre-commit
+- pydata-sphinx-theme>=0.15.4
 - pytest-cov
 - pytest<9.0.0a0
 - python>=3.10,<3.14
@@ -39,6 +41,6 @@ dependencies:
 - sphinx
 - sphinx-copybutton
 - sphinx-markdown-tables
-- sphinx_rtd_theme
+- sphinxcontrib-jquery
 - sysroot_linux-aarch64==2.28
 name: all_cuda-130_arch-aarch64

conda/environments/all_cuda-130_arch-x86_64.yaml

@@ -22,6 +22,7 @@ dependencies:
 - identify>=2.5.20
 - ipython
 - make
+- myst-parser
 - nbsphinx
 - ninja
 - numba-cuda>=0.19.1,<0.20.0a0
@@ -30,6 +31,7 @@ dependencies:
 - numpydoc
 - packaging
 - pre-commit
+- pydata-sphinx-theme>=0.15.4
 - pytest-cov
 - pytest<9.0.0a0
 - python>=3.10,<3.14
@@ -39,6 +41,6 @@ dependencies:
 - sphinx
 - sphinx-copybutton
 - sphinx-markdown-tables
-- sphinx_rtd_theme
+- sphinxcontrib-jquery
 - sysroot_linux-64==2.28
 name: all_cuda-130_arch-x86_64

cpp/include/doxygen_groups.h

@@ -1,5 +1,5 @@
 /*
- * SPDX-FileCopyrightText: Copyright (c) 2023-2024, NVIDIA CORPORATION.
+ * SPDX-FileCopyrightText: Copyright (c) 2023-2025, NVIDIA CORPORATION.
  * SPDX-License-Identifier: Apache-2.0
  */
 
@@ -17,6 +17,26 @@
 // @ingroup tag to the API's doxygen comment.
 // Add a new group by first specifying in the hierarchy below.
 
+/**
+ * @namespace rmm
+ * @brief RAPIDS Memory Manager - The top-level namespace for all RMM functionality
+ *
+ * The rmm namespace provides a comprehensive set of memory management
+ * utilities for CUDA applications, including memory resources, CUDA stream
+ * management, device-side data containers, and memory allocation utilities.
+ */
+
+/**
+ * @namespace rmm::mr
+ * @brief Memory Resource classes and adaptors
+ *
+ * The rmm::mr namespace contains all base memory resource classes that
+ * implement various CUDA memory allocation strategies, adaptors for
+ * suballocation such as pool and arena adaptors, and adaptors that add
+ * functionality such as logging, alignment, and statistics tracking to
+ * existing memory resources.
+ */
+
 /**
  * @defgroup memory_resources Memory Resources
  * @{

dependencies.yaml

@@ -259,14 +259,16 @@ dependencies:
           - graphviz
           - ipython
           - make
+          - myst-parser
           - nbsphinx
           - &numba numba>=0.60.0,<0.62.0a0
           - &numba_cuda numba-cuda>=0.19.1,<0.20.0a0
           - numpydoc
+          - pydata-sphinx-theme>=0.15.4
           - sphinx
-          - sphinx_rtd_theme
           - sphinx-copybutton
           - sphinx-markdown-tables
+          - sphinxcontrib-jquery
   py_version:
     specific:
       - output_types: conda

docs/_static/RAPIDS-logo-purple.png

@@ -46,18 +46,18 @@
 # ones.
 
 extensions = [
-    "sphinxcontrib.jquery",
-    "sphinx.ext.intersphinx",
+    "IPython.sphinxext.ipython_console_highlighting",
+    "IPython.sphinxext.ipython_directive",
+    "breathe",
+    "myst_parser",
+    "nbsphinx",
+    "numpydoc",
     "sphinx.ext.autodoc",
     "sphinx.ext.autosummary",
+    "sphinx.ext.intersphinx",
     "sphinx_copybutton",
-    "numpydoc",
     "sphinx_markdown_tables",
-    "IPython.sphinxext.ipython_console_highlighting",
-    "IPython.sphinxext.ipython_directive",
-    "nbsphinx",
-    "recommonmark",
-    "breathe",
+    "sphinxcontrib.jquery",
 ]
 
 # Breathe Configuration
@@ -95,14 +95,14 @@
 # List of warnings to suppress
 suppress_warnings = []
 
-# if the file deprecated.xml does not exist in the doxygen xml output,
-# breathe will fail to build the docs, so we conditionally add
-# "deprecated.rst" to the exclude_patterns list
+# If the file deprecated.xml does not exist in the Doxygen XML output,
+# Breathe's deprecated page will fail. Conditionally exclude that page
+# and suppress the resulting toctree warning.
 if not os.path.exists(
     os.path.join(breathe_projects["librmm"], "deprecated.xml")
 ):
-    exclude_patterns.append("librmm_docs/deprecated.rst")
-    suppress_warnings.append("toc.excluded")
+    exclude_patterns.append("cpp/deprecated.md")
+    suppress_warnings.append("toc.not_readable")
 
 # The name of the Pygments (syntax highlighting) style to use.
 pygments_style = "sphinx"
@@ -117,18 +117,34 @@
 # a list of builtin themes.
 #
 
-html_theme = "sphinx_rtd_theme"
-
-# Theme options are theme-specific and customize the look and feel of a theme
-# further.  For a list of options available for each theme, see the
-# documentation.
-#
-# html_theme_options = {}
+html_theme = "pydata_sphinx_theme"
+html_logo = "_static/RAPIDS-logo-purple.png"
+
+html_theme_options = {
+    "external_links": [],
+    "icon_links": [
+        {
+            "name": "GitHub",
+            "url": "https://github.com/rapidsai/rmm",
+            "icon": "fa-brands fa-github",
+            "type": "fontawesome",
+        },
+        {
+            "name": "X",
+            "url": "https://x.com/rapidsai",
+            "icon": "fa-brands fa-x-twitter",
+            "type": "fontawesome",
+        },
+    ],
+    "show_toc_level": 1,
+    "navbar_align": "right",
+    "navigation_with_keys": True,
+}
 
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,
 # so a file named "default.css" will overwrite the builtin "default.css".
-html_static_path = []
+html_static_path = ["_static"]
 
 
 # -- Options for HTMLHelp output ------------------------------------------
@@ -300,7 +316,6 @@ def on_missing_reference(app, env, node, contnode):
 
 
 def setup(app):
-    app.add_js_file("copybutton_pydocs.js")
     app.add_css_file("https://docs.rapids.ai/assets/css/custom.css")
     app.add_js_file(
         "https://docs.rapids.ai/assets/js/custom.js", loading_method="defer"