python doc

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

@@ -23,16 +23,18 @@ dependencies:
 - libcufile=1.4.0.31
 - ninja
 - numpy>=1.21
+- numpydoc
 - nvcc_linux-64=11.8
 - nvcomp==2.6.1
 - packaging
 - pre-commit
-- pydata-sphinx-theme
 - pytest
 - pytest-cov
 - python>=3.9,<3.11
 - scikit-build>=0.13.1
 - sphinx
+- sphinx-click
+- sphinx_rtd_theme
 - sysroot_linux-64=2.17
 - zarr
 name: all_cuda-118_arch-x86_64

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

@@ -23,15 +23,17 @@ dependencies:
 - libcufile-dev
 - ninja
 - numpy>=1.21
+- numpydoc
 - nvcomp==2.6.1
 - packaging
 - pre-commit
-- pydata-sphinx-theme
 - pytest
 - pytest-cov
 - python>=3.9,<3.11
 - scikit-build>=0.13.1
 - sphinx
+- sphinx-click
+- sphinx_rtd_theme
 - sysroot_linux-64=2.17
 - zarr
 name: all_cuda-120_arch-x86_64

dependencies.yaml

@@ -236,8 +236,10 @@ dependencies:
     common:
       - output_types: [conda, requirements]
         packages:
-          - pydata-sphinx-theme
+          - numpydoc
           - sphinx
+          - sphinx-click
+          - sphinx_rtd_theme
       - output_types: conda
         packages:
           - doxygen=1.8.20 # pre-commit hook needs a specific version.

docs/source/api.rst

@@ -18,7 +18,6 @@ Zarr
 .. autoclass:: GDSStore
     :members:
 
-
 Defaults
 --------
 .. currentmodule:: kvikio.defaults

docs/source/conf.py

@@ -1,11 +1,10 @@
-#!/usr/bin/env python3
-# Copyright (c) 2022-2023, NVIDIA CORPORATION.
+# -*- coding: utf-8 -*-
 #
 # Configuration file for the Sphinx documentation builder.
 #
-# This file only contains a selection of the most common options. For a full
-# list see the documentation:
-# https://www.sphinx-doc.org/en/master/usage/configuration.html
+# This file does only contain a selection of the most common options. For a
+# full list see the documentation:
+# http://www.sphinx-doc.org/en/master/config
 
 # -- Path setup --------------------------------------------------------------
 
@@ -17,11 +16,10 @@
 # import sys
 # sys.path.insert(0, os.path.abspath('.'))
 
-
 # -- Project information -----------------------------------------------------
 
 project = "kvikio"
-copyright = "2022, NVIDIA"
+copyright = "2023, NVIDIA"
 author = "NVIDIA"
 
 # The short X.Y version.
@@ -32,45 +30,161 @@
 
 # -- General configuration ---------------------------------------------------
 
+# If your documentation needs a minimal Sphinx version, state it here.
+#
+# needs_sphinx = '1.0'
+
 # Add any Sphinx extension module names here, as strings. They can be
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
 extensions = [
     "sphinx.ext.autodoc",
+    "sphinx.ext.mathjax",
+    "sphinx.ext.viewcode",
+    "sphinx.ext.githubpages",
+    "sphinx.ext.autosummary",
+    "sphinx.ext.intersphinx",
+    "sphinx.ext.extlinks",
+    "numpydoc",
+    "sphinx_click",
+    "sphinx_rtd_theme",
 ]
 
+numpydoc_show_class_members = False
+
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ["_templates"]
 
+# The suffix(es) of source filenames.
+# You can specify multiple suffix as a list of string:
+#
+# source_suffix = ['.rst', '.md']
+source_suffix = ".rst"
+
+# The master toctree document.
+master_doc = "index"
+
+# The language for content autogenerated by Sphinx. Refer to documentation
+# for a list of supported languages.
+#
+# This is also used if you do content translation via gettext catalogs.
+# Usually you set "language" from the command line for these cases.
+language = "en"
+
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
 # This pattern also affects html_static_path and html_extra_path.
 exclude_patterns = []
 
+# The name of the Pygments (syntax highlighting) style to use.
+pygments_style = None
+
 
 # -- Options for HTML output -------------------------------------------------
 
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
 #
-html_theme = "pydata_sphinx_theme"
-html_logo = "_static/RAPIDS-logo-purple.png"
-
-html_theme_options = {
-    "external_links": [],
-    # https://github.com/pydata/pydata-sphinx-theme/issues/1220
-    "icon_links": [],
-    "github_url": "https://github.com/rapidsai/kvikio",
-    "twitter_url": "https://twitter.com/rapidsai",
-    "show_toc_level": 1,
-    "navbar_align": "right",
-}
+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 = {}
 
 # 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"]
 
+# Custom sidebar templates, must be a dictionary that maps document names
+# to template names.
+#
+# The default sidebars (for documents that don't match any pattern) are
+# defined by theme itself.  Builtin themes are using these templates by
+# default: ``['localtoc.html', 'relations.html', 'sourcelink.html',
+# 'searchbox.html']``.
+#
+# html_sidebars = {}
+
+
+# -- Options for HTMLHelp output ---------------------------------------------
+
+# Output file base name for HTML help builder.
+htmlhelp_basename = "kvikiodoc"
+
+
+# -- Options for LaTeX output ------------------------------------------------
+
+latex_elements = {
+    # The paper size ('letterpaper' or 'a4paper').
+    #
+    # 'papersize': 'letterpaper',
+    # The font size ('10pt', '11pt' or '12pt').
+    #
+    # 'pointsize': '10pt',
+    # Additional stuff for the LaTeX preamble.
+    #
+    # 'preamble': '',
+    # Latex figure (float) alignment
+    #
+    # 'figure_align': 'htbp',
+}
+
+# Grouping the document tree into LaTeX files. List of tuples
+# (source start file, target name, title,
+#  author, documentclass [howto, manual, or own class]).
+latex_documents = [
+    (master_doc, "kvikio.tex", "kvikio Documentation", "NVIDIA", "manual")
+]
+
+
+# -- Options for manual page output ------------------------------------------
+
+# One entry per manual page. List of tuples
+# (source start file, name, description, authors, manual section).
+man_pages = [(master_doc, "kvikio", "kvikio Documentation", [author], 1)]
+
+
+# -- Options for Texinfo output ----------------------------------------------
+
+# Grouping the document tree into Texinfo files. List of tuples
+# (source start file, target name, title, author,
+#  dir menu entry, description, category)
+texinfo_documents = [
+    (
+        master_doc,
+        "kvikio",
+        "kvikio Documentation",
+        author,
+        "kvikio",
+        "One line description of project.",
+        "Miscellaneous",
+    )
+]
+
+
+# -- Options for Epub output -------------------------------------------------
+
+# Bibliographic Dublin Core info.
+epub_title = project
+
+# The unique identifier of the text. This can be a ISBN number
+# or the project homepage.
+#
+# epub_identifier = ''
+
+# A unique identification for the text.
+#
+# epub_uid = ''
+
+# A list of files that should not be packed into the epub file.
+epub_exclude_files = ["search.html"]
+
+
+# -- Extension configuration -------------------------------------------------
+
 
 def setup(app):
     app.add_css_file("https://docs.rapids.ai/assets/css/custom.css")

docs/source/index.rst

@@ -1,18 +1,26 @@
-Welcome to KvikIO's documentation!
-==================================
+Welcome to KvikIO's Python documentation!
+=========================================
 
-KvikIO is a Python library providing bindings to `cuFile <https://docs.nvidia.com/gpudirect-storage/api-reference-guide/index.html>`_, which enables `GPUDirectStorage <https://developer.nvidia.com/blog/gpudirect-storage/>`_ (GDS).
+KvikIO is a Python and C++ library for high performance file IO. It provides C++ and Python
+bindings to `cuFile <https://docs.nvidia.com/gpudirect-storage/api-reference-guide/index.html>`_,
+which enables `GPUDirect Storage <https://developer.nvidia.com/blog/gpudirect-storage/>`_ (GDS).
+KvikIO also works efficiently when GDS isn't available and can read/write both host and device data seamlessly.
 
-.. toctree::
-   :maxdepth: 2
-   :caption: Contents:
+KvikIO is a part of the `RAPIDS <https://rapids.ai/>`_ suite of open-source software libraries for GPU-accelerated data science.
 
-   api
 
+.. note::
+   This is the documentation for the Python library. For the C++ documentation of KvikIO, see under **libkvikio**.
 
 
-Indices and tables
-==================
+Contents
+--------
 
-* :ref:`genindex`
-* :ref:`search`
+.. toctree::
+   :maxdepth: 1
+   :caption: Getting Started
+
+   install
+   quickstart
+   api
+   genindex

docs/source/install.rst

@@ -0,0 +1,71 @@
+Installation
+============
+
+KvikIO can be installed using Conda/Mamba or from source.
+
+
+Conda/Mamba
+-----------
+
+We strongly recommend to use `mamba <https://github.com/mamba-org/mamba>`_ inplace of conda, which we will do throughout the documents.
+
+Install the **stable release** from the ``rapidsai`` channel like:
+
+.. code-block::
+
+  # Install in existing environment
+  mamba install -c rapidsai -c conda-forge kvikio
+  # Create new environment (CUDA 11.8)
+  mamba create -n kvikio-env -c rapidsai -c conda-forge python=3.10 cuda-version=11.8 kvikio
+  # Create new environment (CUDA 12.0)
+  mamba create -n kvikio-env -c rapidsai -c conda-forge python=3.10 cuda-version=12.0 kvikio
+
+Install the **nightly release** from the ``rapidsai-nightly`` channel like:
+
+.. code-block::
+
+  # Install in existing environment
+  mamba install -c rapidsai-nightly -c conda-forge kvikio
+  # Create new environment (CUDA 11.8)
+  mamba create -n kvikio-env -c rapidsai-nightly -c conda-forge python=3.10 cuda-version=11.8 kvikio
+  # Create new environment (CUDA 12.0)
+  mamba create -n kvikio-env -c rapidsai-nightly -c conda-forge python=3.10 cuda-version=12.0 kvikio
+
+
+.. note::
+
+  If the nightly install doesn't work, set ``channel_priority: flexible`` in your ``.condarc``.
+
+Build from source
+-----------------
+
+In order to setup a development environment run:
+
+.. code-block::
+
+  # CUDA 11.8
+  mamba env create --name kvikio-dev --file conda/environments/all_cuda-118_arch-x86_64.yaml
+  # CUDA 12.0
+  mamba env create --name kvikio-dev --file conda/environments/all_cuda-120_arch-x86_64.yaml
+
+To build and install the extension run:
+
+.. code-block::
+
+  ./build.sh kvikio
+
+
+One might have to define ``CUDA_HOME`` to the path to the CUDA installation.
+
+In order to test the installation, run the following:
+
+.. code-block::
+
+  pytest tests/
+
+
+And to test performance, run the following:
+
+.. code-block::
+
+  python benchmarks/single-node-io.py