Merge branch 'isce-framework:develop' into develop

Author: gshiroma

.github/workflows/build-and-run.yml

@@ -49,6 +49,17 @@ jobs:
               label: Minimum Python supported
               extra-specs: |
                 python=3.9
+          - deps:
+              label: Documentation
+              extra-specs: >-
+                doxygen
+                mkdocs
+                mkdocs-material
+                pdoc
+                pymdown-extensions
+            # Build with CUDA so the Python CUDA extension is documented,
+            # but don't try to run the tests since we're on a CPU-only builder.
+            extra-cmake-args: -DWITH_CUDA=ON
 
     name: Build And Test - ${{ matrix.os.label }} ${{ matrix.deps.label }} ${{ matrix.build-type }}
     runs-on: ${{ matrix.os.runner || 'ubuntu-latest' }}
@@ -75,6 +86,11 @@ jobs:
           create-args: >-
             ${{ env.extra-specs }}
 
+      - name: Install CUDA Toolkit
+        if: matrix.deps.label == 'Documentation'
+        run: |
+          micromamba install -c nvidia cuda
+
       # Fix missing conda command on macOS
       - name: macOS conda command fixup
         if: runner.os == 'macOS'
@@ -98,6 +114,7 @@ jobs:
             -DCMAKE_BUILD_TYPE=${{ env.build-type }} \
             -DCMAKE_INSTALL_PREFIX=$ISCE3_PREFIX \
             -DCMAKE_PREFIX_PATH=$CONDA_PREFIX \
+            ${{ matrix.extra-cmake-args }} \
             .
 
       # Build the project
@@ -125,7 +142,28 @@ jobs:
 
       # Run ctest on the project with the intended test exclusions for this run
       - name: Test Project
+        if: matrix.deps.label != 'Documentation'
         run: |
           cd build
           export GDAL_MEM_ENABLE_OPEN=YES
           ctest --output-on-failure ${{ env.ctest-exclude }}
+
+      - name: Build documentation
+        if: matrix.deps.label == 'Documentation'
+        run: |
+          mkdocs build -d build/docs-output
+
+          # XXX Manually create doxygen output dir, why doesn't CREATE_SUBDIRS in the config work?
+          mkdir -p build/docs-output/api/cxx/
+
+          doxygen build/doc/doxygen/Doxyfile
+          export PYTHONPATH="$PYTHONPATH:$ISCE3_PREFIX/packages"
+
+          pdoc -o build/docs-output/api/python --math install/packages/isce3
+
+      - name: Deploy documentation
+        if: matrix.deps.label == 'Documentation' && github.ref == 'refs/heads/develop'
+        uses: peaceiris/actions-gh-pages@v4
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          publish_dir: ./build/docs-output

.mm/isce3.cxx.tests

@@ -4,7 +4,7 @@
 # the C++ tests
 isce3.cxx.tests.stem := cxx/isce3
 isce3.cxx.tests.prerequisites := isce3.lib
-isce3.cxx.tests.extern := isce3.lib gdal hdf5 mpi eigen fftw pyre gtest
+isce3.cxx.tests.extern := isce3.lib gdal hdf5 eigen fftw pyre gtest
 
 #if there is cuda
 ifdef cuda.dir

.mm/isce3.ext

@@ -7,7 +7,7 @@ isce3.ext.stem := isce3
 isce3.ext.pkg := isce3.pkg
 isce3.ext.wraps := isce3.lib
 isce3.ext.capsule :=
-isce3.ext.extern := gdal hdf5 mpi eigen fftw pyre pybind11 python
+isce3.ext.extern := gdal hdf5 eigen fftw pyre pybind11 python
 
 # if there is cuda
 ifdef cuda.dir

.mm/isce3.lib

@@ -4,7 +4,7 @@
 # the isce3 lib
 isce3.lib.root := cxx/isce3/
 isce3.lib.stem := isce3
-isce3.lib.extern := gdal hdf5 mpi eigen fftw pyre
+isce3.lib.extern := gdal hdf5 eigen fftw pyre
 # if we have cuda
 ifdef cuda.dir
   # add it to the pile of external dependencies

README.md

@@ -37,7 +37,7 @@ https://isce-framework.github.io/isce3/tutorial_tutorial.html)
  - [Python API Reference](
 https://isce-framework.github.io/isce3/sphinx/html/index.html)
  | [C++ API Reference](
-https://isce-framework.github.io/isce3/annotated.html)
+https://isce-framework.github.io/isce3/api/cxx/annotated.html)
  - [Examples](https://github.com/isce-framework/isce3/tree/develop/share)
 
 ## Contributing

doc/doxygen/Doxyfile.in

@@ -30,7 +30,9 @@ PROJECT_NUMBER         = @PROJECT_VERSION@
 # If a relative path is entered, it will be relative to the location
 # where doxygen was started. If left blank the current directory will be used.
 
-OUTPUT_DIRECTORY       = @PROJECT_BINARY_DIR@/docs-output/
+OUTPUT_DIRECTORY       = @PROJECT_BINARY_DIR@/docs-output/api/cxx
+
+CREATE_SUBDIRS = YES
 
 # The OUTPUT_LANGUAGE tag is used to specify the language in which all
 # documentation generated by doxygen is written. Doxygen will use this

doc/doxygen/DoxygenLayout.xml

@@ -27,8 +27,8 @@
       <tab type="user" url="http://trac.osgeo.org/gdal/wiki/DownloadSource" title="Source"/>
       <tab type="user" url="http://trac.osgeo.org/gdal/wiki/DownloadingGdalBinaries" title="Binaries"/>
     </tab> -->
-    <tab type="user" url="sphinx/html/index.html" title="Python classes"/>
-    <tab type="user" url="https://github-fn.jpl.nasa.gov/isce-3/isce/issues/" title="Issue Tracker"/>
+    <tab type="user" url="/isce3/api/python" title="Python API"/>
+    <tab type="user" url="https://github.com/isce-framework/isce3/issues" title="Issue Tracker"/>
     <!-- end ISCE customization -->
   </navindex>
   <!-- Layout definition for a class page -->

doc/doxygen/howtodoc.dox

@@ -1,4 +1,4 @@
-/*! \page howtodoc How to document code in ISCE as a developer?
+/*! \page howtodoc How to document code in ISCE3 as a developer?
 
 \tableofcontents
 
@@ -115,7 +115,7 @@ Doxygen interprets CUDA code in the same manner as C/C++. Use the same style gui
 
 \section docpy Python Documentation
 
-Developers are expected to document their functions using <a href="http://sphinxcontrib-napoleon.readthedocs.io/en/latest/example_google.html">Google Style docstrings</a>. ISCE uses sphinx with the autodoc, autosummary and napoleon extensions. We will base our examples on the code from pyEllipsoid.pyx file in the extensions folder of the source tree. 
+Developers are expected to document their functions using <a href="http://sphinxcontrib-napoleon.readthedocs.io/en/latest/example_google.html">Google Style docstrings</a>. ISCE3 uses sphinx with the autodoc, autosummary and napoleon extensions. We will base our examples on the code from pyEllipsoid.pyx file in the extensions folder of the source tree.
 
 
 \subsection docpyfunc Functions

mkdocs.yml

@@ -4,8 +4,8 @@ theme:
 nav:
   - Home: index.md
   - Installation: buildinstall.md
-  - Python API: api/python/isce3/core.html
-  - C++ API (Unstable): isce3/annotated.html
+  - Python API: api/python/isce3.html
+  - C++ API (Unstable): api/cxx
   - Maintainer Documentation:
       - Release Procedure: maintainer/release-procedure.md
       - Docker Image Updates: maintainer/docker-image-updates.md

python/packages/isce3/core/types.py

@@ -25,6 +25,7 @@ def is_complex32(dataset: h5py.Dataset) -> bool:
     try:
         dtype = dataset.dtype
     except TypeError as e:
+        import re
         regex = re.compile(r"^data type '([<>|=])?c4' not understood$")
         errmsg = str(e)
         if regex.match(errmsg):