diff --git a/ci/build_docs.sh b/ci/build_docs.sh index 956a7389d..d54947106 100755 --- a/ci/build_docs.sh +++ b/ci/build_docs.sh @@ -37,11 +37,11 @@ popd rapids-logger "Build Python docs" pushd python/docs -sphinx-build -b dirhtml . _html -sphinx-build -b text . _text +make dirhtml +make text mkdir -p "${RAPIDS_DOCS_DIR}/rmm/"{html,txt} -mv _html/* "${RAPIDS_DOCS_DIR}/rmm/html" -mv _text/* "${RAPIDS_DOCS_DIR}/rmm/txt" +mv _build/dirhtml/* "${RAPIDS_DOCS_DIR}/rmm/html" +mv _build/text/* "${RAPIDS_DOCS_DIR}/rmm/txt" popd rapids-upload-docs diff --git a/conda/environments/all_cuda-118_arch-x86_64.yaml b/conda/environments/all_cuda-118_arch-x86_64.yaml index 0240b46e5..d56088fbc 100644 --- a/conda/environments/all_cuda-118_arch-x86_64.yaml +++ b/conda/environments/all_cuda-118_arch-x86_64.yaml @@ -9,12 +9,18 @@ dependencies: - cuda-version=11.8 - cudatoolkit - cython>=3.0.0 +- doxygen=1.8.20 - fmt>=9.1.0,<10 - gcovr>=5.0 +- graphviz - identify>=2.5.20 +- ipython +- make +- nbsphinx - ninja - numba>=0.57 - numpy>=1.21 +- numpydoc - nvcc_linux-64=11.8 - pre-commit - pytest @@ -22,5 +28,9 @@ dependencies: - python>=3.9,<3.11 - scikit-build>=0.13.1 - spdlog>=1.11.0,<1.12 +- sphinx +- sphinx-copybutton +- sphinx-markdown-tables +- sphinx_rtd_theme - tomli name: all_cuda-118_arch-x86_64 diff --git a/conda/environments/all_cuda-120_arch-x86_64.yaml b/conda/environments/all_cuda-120_arch-x86_64.yaml index 96b8c8065..baa480a1f 100644 --- a/conda/environments/all_cuda-120_arch-x86_64.yaml +++ b/conda/environments/all_cuda-120_arch-x86_64.yaml @@ -9,17 +9,27 @@ dependencies: - cuda-python>=12.0,<13.0a0 - cuda-version=12.0 - cython>=3.0.0 +- doxygen=1.8.20 - fmt>=9.1.0,<10 - gcovr>=5.0 +- graphviz - identify>=2.5.20 +- ipython +- make +- nbsphinx - ninja - numba>=0.57 - numpy>=1.21 +- numpydoc - pre-commit - pytest - pytest-cov - python>=3.9,<3.11 - scikit-build>=0.13.1 - spdlog>=1.11.0,<1.12 +- sphinx +- sphinx-copybutton +- sphinx-markdown-tables +- sphinx_rtd_theme - tomli name: all_cuda-120_arch-x86_64 diff --git a/dependencies.yaml b/dependencies.yaml index 17fb1d66d..e16d7a292 100644 --- a/dependencies.yaml +++ b/dependencies.yaml @@ -10,6 +10,7 @@ files: - checks - cudatoolkit - develop + - docs - run - test_python test_python: @@ -155,6 +156,7 @@ dependencies: - doxygen=1.8.20 - graphviz - ipython + - make - nbsphinx - numpydoc - sphinx diff --git a/python/docs/Makefile b/python/docs/Makefile index d4bb2cbb9..72d1dcd85 100644 --- a/python/docs/Makefile +++ b/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 ?= +SPHINXOPTS = -n -v -W --keep-going SPHINXBUILD ?= sphinx-build SOURCEDIR = . BUILDDIR = _build diff --git a/python/docs/api.rst b/python/docs/api.rst index 73cd5dd81..b229d8214 100644 --- a/python/docs/api.rst +++ b/python/docs/api.rst @@ -15,6 +15,7 @@ Memory Resources .. automodule:: rmm.mr :members: + :inherited-members: :undoc-members: :show-inheritance: @@ -28,6 +29,7 @@ Memory Allocators .. automodule:: rmm.allocators.numba :members: + :inherited-members: :undoc-members: :show-inheritance: diff --git a/python/docs/basics.md b/python/docs/basics.md index 0c47073c1..997745f00 100644 --- a/python/docs/basics.md +++ b/python/docs/basics.md @@ -91,7 +91,7 @@ example, enabling the `ManagedMemoryResource` tells RMM to use > :warning: The default resource must be set for any device **before** > allocating any device memory on that device. Setting or changing the > resource after device allocations have been made can lead to unexpected -> behaviour or crashes. See [Multiple Devices](#multiple-devices) +> behaviour or crashes. As another example, `PoolMemoryResource` allows you to allocate a large "pool" of device memory up-front. Subsequent allocations will diff --git a/python/docs/conf.py b/python/docs/conf.py index 3010fc069..76b95183e 100644 --- a/python/docs/conf.py +++ b/python/docs/conf.py @@ -113,7 +113,7 @@ # 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 = ["_static"] +html_static_path = [] # -- Options for HTMLHelp output ------------------------------------------ @@ -179,7 +179,10 @@ # Example configuration for intersphinx: refer to the Python standard library. -intersphinx_mapping = {"https://docs.python.org/": None} +intersphinx_mapping = { + "python": ("https://docs.python.org/3", None), + "numba": ("https://numba.readthedocs.io/en/stable", None), +} # Config numpydoc numpydoc_show_inherited_class_members = True @@ -187,6 +190,11 @@ autoclass_content = "init" +nitpick_ignore = [ + ("py:class", "size_t"), + ("py:class", "void"), +] + def setup(app): app.add_js_file("copybutton_pydocs.js") diff --git a/python/rmm/_lib/memory_resource.pyx b/python/rmm/_lib/memory_resource.pyx index aa0d21d1f..0e9277f31 100644 --- a/python/rmm/_lib/memory_resource.pyx +++ b/python/rmm/_lib/memory_resource.pyx @@ -217,18 +217,41 @@ cdef extern from "rmm/mr/device/failure_callback_resource_adaptor.hpp" \ cdef class DeviceMemoryResource: cdef device_memory_resource* get_mr(self): + """Get the underlying C++ memory resource object.""" return self.c_obj.get() def allocate(self, size_t nbytes): + """Allocate ``nbytes`` bytes of memory. + + Parameters + ---------- + nbytes : size_t + The size of the allocation in bytes + """ return self.c_obj.get().allocate(nbytes) def deallocate(self, uintptr_t ptr, size_t nbytes): + """Deallocate memory pointed to by ``ptr`` of size ``nbytes``. + + Parameters + ---------- + ptr : uintptr_t + Pointer to be deallocated + nbytes : size_t + Size of the allocation in bytes + """ self.c_obj.get().deallocate((ptr), nbytes) # See the note about `no_gc_clear` in `device_buffer.pyx`. @cython.no_gc_clear cdef class UpstreamResourceAdaptor(DeviceMemoryResource): + """Parent class for all memory resources that track an upstream. + + Upstream resource tracking requires maintaining a reference to the upstream + mr so that it is kept alive and may be accessed by any downstream resource + adaptors. + """ def __cinit__(self, DeviceMemoryResource upstream_mr, *args, **kwargs): diff --git a/python/rmm/allocators/numba.py b/python/rmm/allocators/numba.py index 18a010e1c..5e87b87b6 100644 --- a/python/rmm/allocators/numba.py +++ b/python/rmm/allocators/numba.py @@ -13,6 +13,7 @@ # limitations under the License. import ctypes +import inspect from cuda.cuda import CUdeviceptr, cuIpcGetMemHandle from numba import config, cuda @@ -112,6 +113,12 @@ def get_ipc_handle(self, memory): ) def get_memory_info(self): + """Returns ``(free, total)`` memory in bytes in the context. + + This implementation raises `NotImplementedError` because the allocation + will be performed using rmm's currently set default mr, which may be a + pool allocator. + """ raise NotImplementedError() @property @@ -119,6 +126,16 @@ def interface_version(self): return 1 +# The parent class docstrings contain references without fully qualified names, +# so we need to replace them here for our Sphinx docs to render properly. +for _, method in inspect.getmembers(RMMNumbaManager, inspect.isfunction): + if method.__doc__ is not None: + method.__doc__ = method.__doc__.replace( + ":class:`BaseCUDAMemoryManager`", + ":class:`numba.cuda.BaseCUDAMemoryManager`", + ) + + # Enables the use of RMM for Numba via an environment variable setting, # NUMBA_CUDA_MEMORY_MANAGER=rmm. See: # https://numba.readthedocs.io/en/stable/cuda/external-memory.html#environment-variable diff --git a/python/rmm/mr.py b/python/rmm/mr.py index ea0a0cf8c..a00d96184 100644 --- a/python/rmm/mr.py +++ b/python/rmm/mr.py @@ -24,6 +24,7 @@ PoolMemoryResource, StatisticsResourceAdaptor, TrackingResourceAdaptor, + UpstreamResourceAdaptor, _flush_logs, _initialize, disable_logging, @@ -51,6 +52,7 @@ "StatisticsResourceAdaptor", "TrackingResourceAdaptor", "FailureCallbackResourceAdaptor", + "UpstreamResourceAdaptor", "_flush_logs", "_initialize", "set_per_device_resource",