Add docs build job

.github/workflows/build.yaml

@@ -52,3 +52,14 @@ jobs:
       branch: ${{ inputs.branch }}
       date: ${{ inputs.date }}
       sha: ${{ inputs.sha }}
+  docs-build:
+    if: ${{ startsWith(github.ref, 'refs/heads/branch-') }}
+    needs: python-build
+    secrets: inherit
+    uses: rapidsai/shared-action-workflows/.github/workflows/custom-job.yaml@branch-23.04
+    with:
+      build_type: branch
+      node_type: "gpu-latest-1"
+      arch: "amd64"
+      container_image: "rapidsai/ci:latest"
+      run_script: "ci/build_docs.sh"

.github/workflows/pr.yaml

@@ -17,6 +17,7 @@ jobs:
       - conda-cpp-tests
       - conda-python-build
       - conda-python-tests
+      - docs-build
     secrets: inherit
     uses: rapidsai/shared-action-workflows/.github/workflows/pr-builder.yaml@branch-23.04
   checks:
@@ -46,3 +47,13 @@ jobs:
     uses: rapidsai/shared-action-workflows/.github/workflows/conda-python-tests.yaml@branch-23.04
     with:
       build_type: pull-request
+  docs-build:
+    needs: conda-python-build
+    secrets: inherit
+    uses: rapidsai/shared-action-workflows/.github/workflows/custom-job.yaml@branch-23.04
+    with:
+      build_type: pull-request
+      node_type: "gpu-latest-1"
+      arch: "amd64"
+      container_image: "rapidsai/ci:latest"
+      run_script: "ci/build_docs.sh"

ci/build_docs.sh

@@ -0,0 +1,46 @@
+#!/bin/bash
+# Copyright (c) 2023, NVIDIA CORPORATION.
+
+set -euo pipefail
+
+rapids-logger "Create test conda environment"
+. /opt/conda/etc/profile.d/conda.sh
+
+rapids-dependency-file-generator \
+  --output conda \
+  --file_key docs \
+  --matrix "cuda=${RAPIDS_CUDA_VERSION%.*};arch=$(arch);py=${RAPIDS_PY_VERSION}" | tee env.yaml
+
+rapids-mamba-retry env create --force -f env.yaml -n docs
+conda activate docs
+
+rapids-print-env
+
+rapids-logger "Downloading artifacts from previous jobs"
+CPP_CHANNEL=$(rapids-download-conda-from-s3 cpp)
+PYTHON_CHANNEL=$(rapids-download-conda-from-s3 python)
+VERSION_NUMBER=$(rapids-get-rapids-version-from-git)
+
+rapids-mamba-retry install \
+  --channel "${CPP_CHANNEL}" \
+  --channel "${PYTHON_CHANNEL}" \
+  libcuspatial \
+  cuspatial
+
+rapids-logger "Build Doxygen docs"
+pushd cpp/doxygen
+doxygen Doxyfile
+popd
+
+rapids-logger "Build Sphinx docs"
+pushd docs
+sphinx-build -b dirhtml source _html -W
+sphinx-build -b text source _text -W
+popd
+
+
+if [[ ${RAPIDS_BUILD_TYPE} == "branch" ]]; then
+  aws s3 sync --delete docs/_html "s3://rapidsai-docs/cuspatial/${VERSION_NUMBER}/html"
+  aws s3 sync --delete docs/_text "s3://rapidsai-docs/cuspatial/${VERSION_NUMBER}/txt"
+  aws s3 sync --delete cpp/doxygen/html "s3://rapidsai-docs/libcuspatial/${VERSION_NUMBER}/html"
+fi

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

@@ -12,17 +12,21 @@ dependencies:
 - cudf=23.04
 - cxx-compiler
 - cython>=0.29,<0.30
+- doxygen
 - gcc_linux-64=9.*
 - gdal>3.5.0,<3.6.0
 - geopandas>=0.11.0
 - gmock=1.10.0
 - gtest=1.10.0
+- ipython
 - libcudf=23.04
 - libcusparse-dev=11.7.5.86
 - libcusparse=11.7.5.86
 - librmm=23.04
 - myst-parser
+- nbsphinx
 - ninja
+- numpydoc
 - nvcc_linux-64=11.8
 - pre-commit
 - pydata-sphinx-theme
@@ -33,5 +37,6 @@ dependencies:
 - rmm=23.04
 - scikit-build>=0.13.1
 - setuptools
+- sphinx<6
 - sysroot_linux-64==2.17
 name: all_cuda-118_arch-x86_64

dependencies.yaml

@@ -10,7 +10,7 @@ files:
       - build_python
       - cudatoolkit
       - develop
-      - doc
+      - docs
       - py_version
       - run_python
       - test_python
@@ -29,6 +29,12 @@ files:
     includes:
       - develop
       - py_version
+  docs:
+    output: none
+    includes:
+      - cudatoolkit
+      - docs
+      - py_version
 channels:
   - rapidsai
   - rapidsai-nightly
@@ -130,12 +136,17 @@ dependencies:
       - output_types: [conda, requirements]
         packages:
           - pre-commit
-  doc:
+  docs:
     common:
-      - output_types: [conda, requirements]
+      - output_types: [conda]
         packages:
-          - pydata-sphinx-theme
+          - doxygen
+          - ipython
           - myst-parser
+          - nbsphinx
+          - numpydoc
+          - pydata-sphinx-theme
+          - sphinx<6
   py_version:
     specific:
       - output_types: conda

docs/source/conf.py

@@ -1,29 +1,4 @@
-#!/usr/bin/env python3
-# -*- coding: utf-8 -*-
-#
-# Copyright (c) 2018, NVIDIA CORPORATION.
-#
-# cuspatial documentation build configuration file, created by
-# sphinx-quickstart on Wed May  3 10:59:22 2017.
-#
-# This file is execfile()d with the current directory set to its
-# containing dir.
-#
-# Note that not all possible configuration values are present in this
-# autogenerated file.
-#
-# All configuration values have a default; values that are commented out
-# serve to show the default.
-
-# If extensions (or modules to document with autodoc) are in another directory,
-# add these directories to sys.path here. If the directory is relative to the
-# documentation root, use os.path.abspath to make it absolute, like shown here.
-#
-import os
-import sys
-
-sys.path.insert(0, os.path.abspath("../.."))
-
+# Copyright (c) 2018-2023, NVIDIA CORPORATION.
 # -- General configuration ------------------------------------------------
 
 # If your documentation needs a minimal Sphinx version, state it here.
@@ -51,6 +26,7 @@
 copybutton_prompt_text = ">>> "
 autosummary_generate = True
 ipython_mplbackend = "str"
+myst_heading_anchors = 3
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ["_templates"]
@@ -83,7 +59,7 @@
 #
 # 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-US"
+language = "en"
 
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.

docs/source/user_guide/cuspatial_api_examples.ipynb

@@ -833,8 +833,6 @@
     "minimum distance from any point in the first linestring of the pair to the nearest segment  \n",
     "or point within the second Linestring of the pair.\n",
     "\n",
-    "<img src=\"attachment:d1e3ced7-837e-43f2-bc78-e24f0af18add.png\" width=250>\n",
-    "\n",
     "The input accepts a pair of geoseries as input sequences of linestring arrays.\n",
     "\n",
     "The below example uses the polygons from `naturalearth_lowres` and treats them as linestrings.  \n",
@@ -1193,7 +1191,6 @@
     "`quadtree_point_in_polygon` depends on a number of intermediate products calculated here using the\n",
     "following functions.\n",
     "\n",
-    "### [cuspatial.polygon_bounding_boxes](https://docs.rapids.ai/api/cuspatial/nightly/api_docs/spatial.html#cuspatial.polygon_bounding_boxes)\n",
     "### [cuspatial.join_quadtree_and_bounding_boxes](https://docs.rapids.ai/api/cuspatial/nightly/api_docs/spatial.html#cuspatial.join_quadtree_and_bounding_boxes)\n",
     "### [cuspatial.quadtree_point_in_polygon](https://docs.rapids.ai/api/cuspatial/nightly/api_docs/spatial.html#cuspatial.quadtree_point_in_polygon)"
    ]

python/cuspatial/cuspatial/core/geoseries.py

@@ -850,7 +850,8 @@ def reset_index(
             return None
 
     def contains_properly(self, other, align=True):
-        """Returns a `Series` of `dtype('bool')` with value `True` for each
+        """
+        Returns a `Series` of `dtype('bool')` with value `True` for each
         aligned geometry that contains _other_.
 
         Compute from a GeoSeries of points and a GeoSeries of polygons which
@@ -869,8 +870,8 @@ def contains_properly(self, other, align=True):
 
         Examples
         --------
-
         Test if a polygon is inside another polygon:
+
         >>> point = cuspatial.GeoSeries(
             [Point(0.5, 0.5)],
             )
@@ -885,6 +886,7 @@ def contains_properly(self, other, align=True):
 
 
         Test whether three points fall within either of two polygons
+
         >>> point = cuspatial.GeoSeries(
             [Point(0, 0)],
             [Point(-1, 0)],
@@ -918,6 +920,7 @@ def contains_properly(self, other, align=True):
         indexed by poly_offsets. If there are rings in poly_ring_offsets that
         are not part of the polygons in poly_offsets, results are likely to be
         incorrect and behavior is undefined.
+
         Note
         ----
         Polygons must be closed: the first and last coordinate of each polygon
@@ -928,6 +931,7 @@ def contains_properly(self, other, align=True):
         result : cudf.Series
             A Series of boolean values indicating whether each point falls
             within the corresponding polygon in the input.
+
         """
         return ContainsProperlyBinpred(self, other, align)()
 

python/cuspatial/cuspatial/core/spatial/distance.py

@@ -66,6 +66,7 @@ def directed_hausdorff_distance(multipoints: GeoSeries):
     y\\ :sub:`0` to the farthest point in ``x`` is 1.414.
 
     Compute the directed hausdorff distances between a set of spaces
+
     >>> pts = cuspatial.GeoSeries([
     ...     MultiPoint([(0, 0), (1, 0)]),
     ...     MultiPoint([(0, 1), (0, 2)])

python/cuspatial/cuspatial/core/spatial/indexing.py

@@ -14,7 +14,8 @@
 def quadtree_on_points(
     xs, ys, x_min, x_max, y_min, y_max, scale, max_depth, max_size
 ):
-    """Construct a quadtree from a set of points for a given area-of-interest
+    """
+    Construct a quadtree from a set of points for a given area-of-interest
     bounding box.
 
     Parameters
@@ -72,23 +73,18 @@ def quadtree_on_points(
     -----
 
     * Swaps ``min_x`` and ``max_x`` if ``min_x > max_x``
-
     * Swaps ``min_y`` and ``max_y`` if ``min_y > max_y``
-
     * 2D coordinates are converted into a 1D Morton code by dividing each x/y
-    by the ``scale``: (``(x - min_x) / scale`` and ``(y - min_y) / scale``).
-
+      by the ``scale``: (``(x - min_x) / scale`` and ``(y - min_y) / scale``).
     * `max_depth` should be less than 16, since Morton codes are represented
-    as `uint32_t`. The eventual number of levels may be less than `max_depth`
-    if the number of points is small or `max_size` is large.
-
+      as `uint32_t`. The eventual number of levels may be less than `max_depth`
+      if the number of points is small or `max_size` is large.
     * All intermediate quadtree nodes will have fewer than `max_size` number of
-    points. Leaf nodes are permitted (but not guaranteed) to have >= `max_size`
-    number of points.
+      points. Leaf nodes are permitted (but not guaranteed) to have >=
+      `max_size` number of points.
 
     Examples
     --------
-
     An example of selecting the ``max_size`` and ``scale`` based on input::
 
         >>> np.random.seed(0)

python/cuspatial/cuspatial/core/spatial/join.py

@@ -70,12 +70,11 @@ def point_in_polygon(
     -----
 
     * input Series x and y will not be index aligned, but computed as
-    sequential arrays.
-
+      sequential arrays.
     * poly_ring_offsets must contain only the rings that make up the polygons
-    indexed by poly_offsets. If there are rings in poly_ring_offsets that
-    are not part of the polygons in poly_offsets, results are likely to be
-    incorrect and behavior is undefined.
+      indexed by poly_offsets. If there are rings in poly_ring_offsets that
+      are not part of the polygons in poly_offsets, results are likely to be
+      incorrect and behavior is undefined.
 
     Returns
     -------