Generate unified Python/C++ docs

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

@@ -4,6 +4,7 @@ channels:
 - rapidsai
 - conda-forge
 dependencies:
+- breathe
 - c-compiler
 - clang-tools==16.0.6
 - clang==16.0.6

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

@@ -4,6 +4,7 @@ channels:
 - rapidsai
 - conda-forge
 dependencies:
+- breathe
 - c-compiler
 - clang-tools==16.0.6
 - clang==16.0.6

dependencies.yaml

@@ -174,6 +174,7 @@ dependencies:
     common:
       - output_types: conda
         packages:
+          - breathe
           - *doxygen
           - graphviz
           - ipython

include/rmm/device_uvector.hpp

@@ -44,7 +44,7 @@ namespace rmm {
  * `thrust::uninitialized_fill`.
  *
  * Example:
- * @code{c++}
+ * @code{.cpp}
  * rmm::mr::device_memory_resource * mr = new my_custom_resource();
  * rmm::cuda_stream_view s{};
  *

include/rmm/logger.hpp

@@ -98,7 +98,9 @@ struct bytes {
 
 /**
  * @brief Returns the global RMM logger
- * @addtogroup logging
+ *
+ * @ingroup logging
+ *
  * This is a spdlog logger. The easiest way to log messages is to use the `RMM_LOG_*` macros.
  *
  * @return spdlog::logger& The logger.

include/rmm/mr/device/device_memory_resource.hpp

@@ -75,7 +75,7 @@ namespace rmm::mr {
  * pool_memory_resource objects for each device and sets them as the per-device resource for that
  * device.
  *
- * @code{c++}
+ * @code{.cpp}
  * std::vector<unique_ptr<pool_memory_resource>> per_device_pools;
  * for(int i = 0; i < N; ++i) {
  *   cudaSetDevice(i);

include/rmm/mr/device/failure_callback_resource_adaptor.hpp

@@ -60,7 +60,7 @@ using failure_callback_t = std::function<bool(std::size_t, void*)>;
  * When implementing a callback function for allocation retry, care must be taken to avoid an
  * infinite loop. The following example makes sure to only retry the allocation once:
  *
- * @code{c++}
+ * @code{.cpp}
  * using failure_callback_adaptor =
  *   rmm::mr::failure_callback_resource_adaptor<rmm::mr::device_memory_resource>;
  *

include/rmm/mr/device/per_device_resource.hpp

@@ -61,7 +61,7 @@
  * pool_memory_resource objects for each device and sets them as the per-device resource for that
  * device.
  *
- * @code{c++}
+ * @code{.cpp}
  * std::vector<unique_ptr<pool_memory_resource>> per_device_pools;
  * for(int i = 0; i < N; ++i) {
  *   cudaSetDevice(i);

include/rmm/mr/device/polymorphic_allocator.hpp

@@ -133,7 +133,7 @@ bool operator!=(polymorphic_allocator<T> const& lhs, polymorphic_allocator<U> co
  *`deallocate` functions.
  *
  * Example:
- *\code{c++}
+ *\code{.cpp}
  * my_stream_ordered_allocator<int> a{...};
  * cuda_stream_view s = // create stream;
  *

python/docs/Makefile

@@ -3,7 +3,7 @@
 
 # You can set these variables from the command line, and also
 # from the environment for the first two.
-SPHINXOPTS    = -n -v -W --keep-going
+SPHINXOPTS    = -n -v
 SPHINXBUILD   ?= sphinx-build
 SOURCEDIR     = .
 BUILDDIR      = _build

python/docs/conf.py

@@ -46,8 +46,12 @@
     "IPython.sphinxext.ipython_directive",
     "nbsphinx",
     "recommonmark",
+    "breathe",
 ]
 
+# Breathe Configuration
+breathe_projects = {"librmm": "../../doxygen/xml"}
+breathe_default_project = "librmm"
 
 copybutton_prompt_text = ">>> "
 
@@ -197,9 +201,16 @@
 ]
 
 
+# def on_missing_reference(app, env, node, contnode):
+#     if node["refdomain"] == "cpp":
+#         return contnode
+#     return None
+
+
 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"
     )
+    # app.connect("missing-reference", on_missing_reference)

python/docs/cpp.rst

@@ -0,0 +1,8 @@
+Welcome to the rmm C++ documentation!
+========================================
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Contents:
+
+   cpp_api.rst

python/docs/cpp_api.rst

@@ -0,0 +1,8 @@
+API Reference
+=============
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Contents:
+
+   librmm_docs/index

python/docs/basics.md → python/docs/guide.md

@@ -1,4 +1,4 @@
-# RMM - the RAPIDS Memory Manager
+# User Guide
 
 Achieving optimal performance in GPU-centric workflows frequently requires
 customizing how GPU ("device") memory is allocated.

python/docs/index.rst

@@ -10,8 +10,8 @@ Welcome to rmm's documentation!
    :maxdepth: 2
    :caption: Contents:
 
-   basics.md
-   api.rst
+   Python <python.rst>
+   C++ <cpp.rst>
 
 
 Indices and tables

python/docs/librmm_docs/cuda_device_management.rst

@@ -0,0 +1,5 @@
+CUDA Device Management
+======================
+
+.. doxygengroup:: cuda_device_management
+   :members:

python/docs/librmm_docs/cuda_streams.rst

@@ -0,0 +1,5 @@
+CUDA Streams
+============
+
+.. doxygengroup:: cuda_streams
+   :members:

python/docs/librmm_docs/data_containers.rst

@@ -0,0 +1,5 @@
+Data Containers
+===============
+
+.. doxygengroup:: data_containers
+   :members:

python/docs/librmm_docs/errors.rst

@@ -0,0 +1,5 @@
+Errors
+======
+
+.. doxygengroup:: errors
+   :members:

python/docs/librmm_docs/index.rst

@@ -0,0 +1,29 @@
+.. rmm documentation master file, created by
+   sphinx-quickstart on Thu Nov 19 13:16:00 2020.
+   You can adapt this file completely to your liking, but it should at least
+   contain the root `toctree` directive.
+
+librmm Documentation
+====================
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Contents:
+
+   memory_resources
+   data_containers
+   thrust_integrations
+   cuda_device_management
+   cuda_streams
+   errors
+   logging
+
+
+.. doxygennamespace:: rmm
+   :desc-only:
+
+Indices and tables
+==================
+
+* :ref:`genindex`
+* :ref:`search`

python/docs/librmm_docs/logging.rst

@@ -0,0 +1,5 @@
+Logging
+=======
+
+.. doxygengroup:: logging
+   :members:

python/docs/librmm_docs/memory_resources.rst

@@ -0,0 +1,17 @@
+Memory Resources
+================
+
+.. doxygennamespace:: rmm::mr
+   :desc-only:
+
+.. doxygengroup:: memory_resources
+   :desc-only:
+
+.. doxygengroup:: device_memory_resources
+   :members:
+
+.. doxygengroup:: host_memory_resources
+   :members:
+
+.. doxygengroup:: device_resource_adaptors
+   :members:

python/docs/librmm_docs/thrust_integrations.rst

@@ -0,0 +1,5 @@
+Thrust Integration
+==================
+
+.. doxygengroup:: thrust_integrations
+   :members:

python/docs/python.rst

@@ -0,0 +1,9 @@
+Welcome to the rmm Python documentation!
+========================================
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Contents:
+
+   guide.md
+   python_api.rst