Add docs build job (#536)

The PR adds a `docs_build` process to the PR and Build workflows for this repository. The generated docs are synced to s3 for only the build workflows.

Authors:
  - Jake Awe (https://github.com/AyodeAwe)
  - AJ Schmidt (https://github.com/ajschmidt8)

Approvers:
  - AJ Schmidt (https://github.com/ajschmidt8)
  - Adam Thompson (https://github.com/awthomp)

URL: #536

Author: AyodeAwe

.github/workflows/build.yaml

@@ -43,3 +43,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/[email protected]
+    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

@@ -16,6 +16,7 @@ jobs:
       - conda-python-build
       - conda-python-tests
       - conda-notebook-tests
+      - docs-build
     secrets: inherit
     uses: rapidsai/shared-action-workflows/.github/workflows/[email protected]
   checks:
@@ -43,3 +44,13 @@ jobs:
       arch: "amd64"
       container_image: "rapidsai/ci:latest"
       run_script: "ci/test_notebooks.sh"
+  docs-build:
+    needs: conda-python-build
+    secrets: inherit
+    uses: rapidsai/shared-action-workflows/.github/workflows/[email protected]
+    with:
+      build_type: pull-request
+      node_type: "gpu-latest-1"
+      arch: "amd64"
+      container_image: "rapidsai/ci:latest"
+      run_script: "ci/build_docs.sh"

.gitignore

@@ -9,3 +9,5 @@ lib64
 *.fatbin
 docs/build
 *.ipynb_checkpoints
+docs/_html
+docs/_text

ci/build_docs.sh

@@ -0,0 +1,37 @@
+#!/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"
+PYTHON_CHANNEL=$(rapids-download-conda-from-s3 python)
+VERSION_NUMBER=$(rapids-get-rapids-version-from-git)
+
+rapids-mamba-retry install \
+  --channel "${PYTHON_CHANNEL}" \
+  cusignal
+
+rapids-logger "Build Sphinx docs"
+pushd docs
+sphinx-build -b dirhtml source _html
+sphinx-build -b text source _text
+popd
+
+
+if [[ ${RAPIDS_BUILD_TYPE} == "branch" ]]; then
+  aws s3 sync --delete docs/_html "s3://rapidsai-docs/cusignal/${VERSION_NUMBER}/html"
+  aws s3 sync --delete docs/_text "s3://rapidsai-docs/cusignal/${VERSION_NUMBER}/txt"
+fi

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

@@ -13,12 +13,16 @@ dependencies:
 - notebook
 - numba >=0.49.0
 - numpy >=1.19,<1.24
+- numpydoc
 - pre-commit
+- pydata-sphinx-theme
 - pytest
 - pytest-benchmark
 - pytest-cov
 - pytest-xdist
 - python>=3.8,<3.11
 - pytorch <=1.12.1
 - scipy >=1.6.0
+- sphinx-copybutton
+- sphinx<6
 name: all_cuda-118_arch-x86_64

dependencies.yaml

@@ -8,6 +8,7 @@ files:
     includes:
       - checks
       - cudatoolkit
+      - docs
       - py_version
       - run
       - test_notebooks
@@ -29,6 +30,12 @@ files:
     includes:
       - checks
       - py_version
+  docs:
+    output: none
+    includes:
+      - cudatoolkit
+      - docs
+      - py_version
 channels:
   - rapidsai
   - rapidsai-nightly
@@ -60,6 +67,15 @@ dependencies:
       - output_types: [conda, requirements]
         packages:
           - pre-commit
+  docs:
+    common:
+      - output_types: [conda, requirements]
+        packages:
+          - ipython
+          - numpydoc
+          - pydata-sphinx-theme
+          - sphinx<6
+          - sphinx-copybutton
   py_version:
     specific:
       - output_types: conda

docs/source/api.rst

@@ -4,24 +4,24 @@ cuSignal API Reference
 
 
 Convolution
-============
+===========
 
 Convolve
-------------
+--------
 
 .. automodule:: cusignal.convolution.convolve
     :members:
     :undoc-members:
 
 Correlate
-------------
+---------
 .. automodule:: cusignal.convolution.correlate
     :members:
     :undoc-members:
 
 
 Modulation/Demodulation
-============
+=======================
 
 Demodulation
 ------------
@@ -31,28 +31,28 @@ Demodulation
     :undoc-members:
 
 Estimation
-============
+==========
 
 Kalman Filter
-------------
+-------------
 
 .. automodule:: cusignal.estimation.filters
     :members:
     :undoc-members:
 
 
 Filtering
-============
+=========
 
 Resample
-------------
+--------
 
 .. automodule:: cusignal.filtering.resample
     :members:
     :undoc-members:
 
 FIR Filters
-------------
+-----------
 
 .. automodule:: cusignal.filtering.filtering.firfilter
     :members:
@@ -63,17 +63,17 @@ FIR Filters
     :undoc-members:
 
 Channelizer
-------------
+-----------
 
 .. automodule:: cusignal.filtering.channelize_poly
     :members:
     :undoc-members:
 
 Filter Design
-============
+=============
 
 Resample
-------------
+--------
 
 .. automodule:: cusignal.filter_design.fir_filter_design
     :members:
@@ -92,108 +92,108 @@ Peak Finding
 
 
 Window Functions
-============
+================
 
 Windows
-------------
+-------
 
 .. automodule:: cusignal.windows.windows
     :members:
     :undoc-members:
 
 
 Waveforms
-============
+=========
 
 Waveform Generation
-------------
+-------------------
 
 .. automodule:: cusignal.waveforms.waveforms
     :members:
     :undoc-members:
 
 
 Spectrum Analysis
-============
+=================
 
 Spectral
-------------
+--------
 
 .. automodule:: cusignal.spectral_analysis.spectral
     :members:
     :undoc-members:
 
 Acoustics
-------------
+---------
 
 .. automodule:: cusignal.acoustics.cepstrum
     :members:
     :undoc-members:
 
 
 Wavelets
-============
+========
 
 Wavelets
-------------
+--------
 
 .. automodule:: cusignal.wavelets.wavelets
     :members:
     :undoc-members:
 
 
 B-splines
-============
+=========
 
 B-splines
-------------
+---------
 
 .. automodule:: cusignal.bsplines.bsplines
     :members:
     :undoc-members:
 
 
 Utilities
-============
+=========
 
 Array Tools
-------------
+-----------
 
 .. automodule:: cusignal.utils.arraytools
     :members:
     :undoc-members:
 
 FFTPack Helper
-------------
+--------------
 
 .. automodule:: cusignal.utils.fftpack_helper
     :members:
     :undoc-members:
 
 
 IO
-============
+==
 
 Reader
-------------
+------
 
 .. automodule:: cusignal.io.reader
     :members:
     :undoc-members:
 
 Writer
-------------
+------
 
 .. automodule:: cusignal.io.writer
     :members:
     :undoc-members:
 
 
 Radar/Phased Array
-============
+==================
 
 Radar Tools
-------------
+-----------
 
 .. automodule:: cusignal.radartools.radartools
     :members:

docs/source/conf.py

@@ -1,28 +1,4 @@
-#!/usr/bin/env python3
-# -*- coding: utf-8 -*-
-#
 # Copyright (c) 2018-2022, NVIDIA CORPORATION.
-#
-# pygdf 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('../..'))
-
 # -- General configuration ------------------------------------------------
 
 # If your documentation needs a minimal Sphinx version, state it here.
@@ -77,7 +53,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 = None
+language = 'en'
 
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.

python/cusignal/filtering/filtering.py

@@ -1140,11 +1140,11 @@ def channelize_poly(x, h, n_chans):
         Number of channels for channelizer
 
     Returns
-    ----------
+    -------
     yy : channelized output matrix
 
     Notes
-    ----------
+    -----
     Currently only supports simple channelizer where channel
     spacing is equivalent to the number of channels used (zero overlap).
     Number of filter taps (len of filter / n_chans) must be <=32.