Doc updates and deploy (#448)

* Updated docs and build process

* Added doc workflow

* Removed doc deploy from gitlab ci

* Added missing cmakelists file

* Disable doc build in ci pipeline

* Set python version in doc deploy

* Fixed python version and added doxygen as a dependency

* Fixed define and added enc check stage to doc build

* More debugging

* Update AWS action

* Trying different AWS checkout

* Added role to assume

* Added permissions section

* Reverted to old commit

* Brought pipeline back inline with ARD pipeline

* Changed to artifact upload and download

* Added missing index.rst

.github/workflows/aws_doc_deploy.yml

+name: aws-doc-deploy
+
+on:
+  workflow_run:
+    workflows: ["Build-Docs"]
+    branches: [main]
+    types: 
+      - completed
+
+jobs:
+  deploy:
+    if: ${{ github.event.workflow_run.conclusion == 'success' }}
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        shell: bash -el {0}
+    steps:
+      - uses: actions/checkout@c85c95e3d7251135ab7dc9ce3241c5835cc595a9
+        with:
+          submodules: true
+          fetch-depth: 0
+      - uses: actions/download-artifact@v9bc31d5ccc31df68ecc42ccf4149144866c47d8a
+        with:
+          name: docs_folder
+            
+      - name: Set AWS credentials for upload
+        uses: aws-actions/configure-aws-credentials@0e613a0980cbf65ed5b322eb7a1e075d28913a83
+        with:
+          aws-access-key-id: ${{ secrets.AWS_ACCESS_KEY_ID }}
+          aws-secret-access-key: ${{ secrets.AWS_SECRET_ACCESS_KEY }}
+          aws-region: us-west-2
+      
+      - name: Upload to S3
+        working-directory: docs/public
+        run: |
+          cd docs
+          aws s3 sync --delete public s3://asc-docs/usgscsm
\ No newline at end of file

.github/workflows/ci_testing.yml

@@ -20,10 +20,10 @@ jobs:
       run:
         shell: bash -l {0}
     steps:
-      - uses: actions/checkout@v2
+      - uses: actions/checkout@c85c95e3d7251135ab7dc9ce3241c5835cc595a9
         with:
           submodules: true
-      - uses: conda-incubator/setup-miniconda@v2
+      - uses: conda-incubator/setup-miniconda@3b0f2504dd76ef23b6d31f291f4913fb60ab5ff3
         with:
           miniconda-version: "latest"
           activate-environment: usgscsm
@@ -38,9 +38,42 @@ jobs:
         run: |
           mkdir -p build
           cd build
-          cmake -DCMAKE_BUILD_TYPE=RELEASE -DUSGSCSM_EXTERNAL_DEPS=ON ..
+          cmake -DCMAKE_BUILD_TYPE=RELEASE -DUSGSCSM_EXTERNAL_DEPS=ON -DUSGSCSM_BUILD_DOCS=OFF ..
           cmake --build .
       - name: Test Package
         run: |
           cd build
           ctest -VV
+  
+  Build-Docs:
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        shell: bash -el {0}
+    steps:
+      - uses: actions/checkout@c85c95e3d7251135ab7dc9ce3241c5835cc595a9
+        with:
+          submodules: true
+          fetch-depth: 0
+      - uses: conda-incubator/setup-miniconda@3b0f2504dd76ef23b6d31f291f4913fb60ab5ff3
+        with:
+          miniconda-version: "latest"
+          activate-environment: usgscsm
+          environment-file: doc_environment.yml
+          auto-activate-base: false
+          auto-update-conda: true
+
+      - name: Check doc build environment
+        run: |
+          conda list
+
+      - name: Build Docs
+        run: |
+          cd docs
+          doxygen Doxyfile.in
+          sphinx-build -b html source public
+
+      - uses: actions/upload-artifact@0b7f8abb1508181956e8e162db84b466c27e18ce
+        with:
+          name: docs_folder
+          path: docs/public/
\ No newline at end of file

CMakeLists.txt

 cmake_minimum_required(VERSION 3.10)
 project(usgscsm VERSION 1.7.0 DESCRIPTION "usgscsm library")
 
+list(APPEND CMAKE_MODULE_PATH "${CMAKE_CURRENT_SOURCE_DIR}/cmake")
+
+message(STATUS "CMake Module Path: " ${CMAKE_MODULE_PATH})
+
 include(GNUInstallDirs)
 
 set(CMAKE_CXX_STANDARD 11)
@@ -129,3 +133,11 @@ if(USGSCSM_BUILD_TESTS)
   add_subdirectory(tests)
 
 endif()
+
+option (USGSCSM_BUILD_DOCS "Build the USGSCSM Docs" ON)
+if(USGSCSM_BUILD_DOCS)
+  add_subdirectory ("docs")
+else()
+  message(STATUS "Skipping Docs")
+endif()
+

doc_environment.yml

@@ -4,8 +4,8 @@ channels:
   - default
 
 dependencies:
+  - breathe
   - cmake>=3.12
-  - ale
   - csm
+  - doxygen
   - nlohmann_json
-  - breathe

docs/CMakeLists.txt

+message(STATUS "Setting Up Docs")
+
+find_package(Doxygen REQUIRED)
+find_package(Sphinx REQUIRED)
+
+# Find all the public headers
+set(USGSCSM_BUILD_INCLUDE_DIR "${CMAKE_CURRENT_SOURCE_DIR}/include/usgscsm")
+file(GLOB_RECURSE USGSCSM_PUBLIC_HEADERS ${USGSCSM_BUILD_INCLUDE_DIR}/*.h)
+
+set(DOXYGEN_INPUT_DIR ${PROJECT_SOURCE_DIR}/usgscsm/include/)
+set(DOXYGEN_OUTPUT_DIR ${CMAKE_CURRENT_BINARY_DIR})
+set(DOXYGEN_INDEX_FILE ${DOXYGEN_OUTPUT_DIR}/xml/index.xml)
+set(DOXYFILE_IN ${CMAKE_CURRENT_SOURCE_DIR}/Doxyfile.in)
+set(DOXYFILE_OUT ${CMAKE_CURRENT_BINARY_DIR}/Doxyfile)
+
+configure_file(${DOXYFILE_IN} ${DOXYFILE_OUT} @ONLY)
+
+message(STATUS "DOXYGEN_INPUT_DIR: " ${DOXYGEN_INPUT_DIR})
+message(STATUS "DOXYGEN_OUTPUT_DIR: " ${DOXYGEN_OUTPUT_DIR})
+message(STATUS "DOXYGEN_INDEX_FILE: " ${DOXYGEN_INDEX_FILE})
+message(STATUS "DOXYFILE_IN: " ${DOXYFILE_IN})
+message(STATUS "DOXYFILE_OUT: " ${DOXYFILE_OUT})
+
+file(MAKE_DIRECTORY ${DOXYGEN_OUTPUT_DIR})
+
+add_custom_command(OUTPUT ${DOXYGEN_INDEX_FILE}
+                   DEPENDS ${USGSCSM_PUBLIC_HEADERS}
+                   COMMAND ${DOXYGEN_EXECUTABLE} ${DOXYFILE_OUT} 
+                   WORKING_DIRECTORY ${CMAKE_CURRENT_SOURCE_DIR}
+                   MAIN_DEPENDENCY Doxyfile
+                   COMMENT "Generating docs"
+                   VERBATIM)
+
+add_custom_target(Doxygen ALL DEPENDS ${DOXYGEN_INDEX_FILE})
+
+set(SPHINX_SOURCE ${CMAKE_CURRENT_SOURCE_DIR}/source)
+set(SPHINX_BUILD ${CMAKE_CURRENT_BINARY_DIR}/sphinx)
+set(SPHINX_INDEX_FILE ${SPHINX_BUILD}/index.html)
+
+set(SPHINX_RST_FILES ${CMAKE_CURRENT_SOURCE_DIR}/source/index.rst)
+
+add_custom_command(OUTPUT ${SPHINX_INDEX_FILE}
+                   COMMAND
+                     ${SPHINX_EXECUTABLE} -b html
+                     # Tell Breathe where to find the Doxygen output
+                     -Dbreathe_projects.SpiceQL=${DOXYGEN_OUTPUT_DIR}/xml
+                   ${SPHINX_SOURCE} ${SPHINX_BUILD}
+                   WORKING_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}
+                   DEPENDS ${USGSCSM_PUBLIC_HEADERS}
+                   # Other docs files you want to track should go here (or in some variable)
+                   ${SPHINX_RST_FILES}
+                   ${CMAKE_CURRENT_SOURCE_DIR}/../README.md # Docs insert the readme, so it's a dep
+                   ${DOXYGEN_INDEX_FILE}
+                   # MAIN_DEPENDENCY ${SPHINX_SOURCE}/conf.py
+                   COMMENT "Generating documentation with Sphinx")
+
+
+# Nice named target so we can run the job easily
+add_custom_target(Sphinx ALL DEPENDS ${SPHINX_INDEX_FILE})
+
+# Add an install target to install the docs
+include(GNUInstallDirs)
+install(DIRECTORY ${SPHINX_BUILD}
+DESTINATION ${CMAKE_INSTALL_DOCDIR})
+

docs/Makefile

-# Minimal makefile for Sphinx documentation
-#
-
-# You can set these variables from the command line, and also
-# from the environment for the first two.
-SPHINXOPTS    ?=
-SPHINXBUILD   ?= sphinx-build
-SOURCEDIR     = source
-BUILDDIR      = build
-
-# Put it first so that "make" without argument is like "make help".
-help:
-	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
-
-.PHONY: help Makefile
-
-# Catch-all target: route all unknown targets to Sphinx using the new
-# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
-%: Makefile
-	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

docs/source/conf.py

@@ -17,7 +17,7 @@
 
 # -- Project information -----------------------------------------------------
 
-project = 'usgscsm'
+project = 'USGSCSM'
 copyright = '2021, USGS Astrogeology Software Team'
 author = 'USGS Astrogeology Software Team'
 
@@ -51,8 +51,8 @@ html_theme = 'alabaster'
 html_static_path = ['_static']
 
 # breathe (doxygen -> sphinx package) settings
-breathe_projects = { "usgscsm": "../xml/" }
-breathe_default_project = "usgscsm"
+breathe_projects = { "USGSCSM": "../xml/" }
+breathe_default_project = "USGSCSM"
 
 import subprocess, os
 

docs/source/index.rst

-Welcome to usgscsm's documentation!
+Welcome to USGSCSM's documentation!
 ===================================
 
 :Release: |version|
@@ -14,6 +14,10 @@ This project is hosted on `GitHub`_. If you run into a problem, please open an `
    :maxdepth: 2
 
    library/index
+   sensors/index
+   user/creating_an_environment
+   user/isd_generation
+   tools/usgscsm_cam_test
 
 .. _GitHub: http://github.com/USGS-Astrogeology/usgscsm
 .. _issue: https://github.com/USGS-Astrogeology/usgscsm/issues?state=open

docs/source/library/distortion.rst

@@ -2,6 +2,6 @@ USGSCSM Distortion Class
 ==============================================
 
 .. doxygenfile:: Distortion.h
-   :project: usgscsm
+   :project: USGSCSM
 
 

docs/source/library/framer.rst

@@ -2,5 +2,5 @@ USGSCSM Astro Frame Sensor Model Class
 =======================================================
 
 .. doxygenfile:: UsgsAstroFrameSensorModel.h
-   :project: usgscsm
+   :project: USGSCSM
 

docs/source/library/linescanner.rst

@@ -2,5 +2,5 @@ USGSCSM Astro Linescan Sensor Model Class
 =============================================================
 
 .. doxygenfile:: UsgsAstroLsSensorModel.h
-   :project: usgscsm
+   :project: USGSCSM
 

docs/source/library/plugin.rst

@@ -2,5 +2,5 @@ USGSCSM Astro Plugin Class
 =====================================================
 
 .. doxygenfile:: UsgsAstroPlugin.h
-   :project: usgscsm
+   :project: USGSCSM
 

docs/source/library/sar.rst

@@ -2,5 +2,5 @@ USGSCSM Astro SAR Sensor Model Class
 =============================================================
 
 .. doxygenfile:: UsgsAstroSarSensorModel.h
-   :project: usgscsm
+   :project: USGSCSM
 

docs/source/library/utilities.rst

@@ -2,5 +2,5 @@ USGSCSM Utilities Class
 ==============================================
 
 .. doxygenfile:: Utilities.h
-   :project: usgscsm
+   :project: USGSCSM
 

docs/source/sensors/Cassini.rst

@@ -6,6 +6,8 @@ wide angle camera contains 18 filters.
 
 Processing Cassini ISS Images
 -----------------------------
+.. code-block:: python
+
   import ale, json, os
   from ale.drivers.cassini_drivers import CassiniIssPds3LabelNaifSpiceDriver
   from ale.drivers import JsonEncoder

docs/source/sensors/Selene.rst

@@ -9,6 +9,8 @@ Processing Kaguya TC Images
 ---------------------------
 Begin by generating an ISD as described in the section on :ref:`isd_generation`.
 
+.. code-block:: python
+
     import json
     import os
     import csmapi

docs/source/sensors/index.rst

+#####################################
+Cameras that can be used with USGSCSM
+#####################################
+
+.. toctree::
+  Cassini
+  Dawn
+  Galileo
+  Hayabusa
+  Juno
+  LunarReconnaissanceOrbiter
+  MarsExpress
+  MarsReconnaissanceOrbiter
+  Messenger
+  NewHorizons
+  Odyssey
+  Selene
+  TraceGasOrbiter
+  Viking
+  Voyager

docs/source/user/isd_generation.rst

 .. _isd_generation:
 
 Creating and testing an ISD
-===
+===========================
 
 This tutorial assumes that the user has created a conda environment with ale, usgscsm,
 and csmapi installed.
 
 Generating an ISD with ALE
------------------
+--------------------------
 ISD generation is the first step in processing an image with the models provided
 by USGSCSM.  ISDs can be easily generated with the use of
 `ALE <https://github.com/USGS-Astrogeology/ale>`_, which generates ISDs through
 the use of the "load" and "loads" functions  After installing the library
 (as described on the repository), one can generate an ISD using the image's label
-in the following fashion::
+in the following fashion:
+
+.. code-block:: python
 
     import ale
 
@@ -29,30 +31,19 @@ Under these circumstances, the user must explicitly pass the desired kernel set
 to the loads function.  This kernel set can be generated from a spiceinit'd cub
 and passed to ale as follows:
 
+.. code-block:: python
+
     kernels = ale.util.generate_kernels_from_cube(spice_initted_cub, expand=True)
     isd = ale.loads(img_file, props={'kernels': kernels})
 
 After generating the ISD in Python, it is necessary to save it to disc. This is
 accomplished via Python builtin functions such as:
 
+.. code-block:: python
+
     with open('out.json', 'w') as f:
         f.write(isd)
 
-Generating an ISD with Pfeffernusse
--------------
-Alternatively, ISDs can be generated via web service through the API exposed by
-`Pfeffernusse <https://app.swaggerhub.com/apis/USGS-Astro/pfeffernusse2/0.1.4-oas3>`_.
-While the web service is not yet publicly hosted, a public version of the service
-is under development.  Individuals or organizations may choose to host their own
-service, and it can be accessed as follows::
-
-    curl -X POST "http://<servername>:<port>/v1/pds/" -H \
-    "accept: application/json" -H "Content-Type: application/json" \
-    -d @EN1040199536M_tmp.json
-
-where EN1040199536M_tmp.json is a file containing a JSON representation of an
-image label.
-
 Testing the ISD
 ---------------
 USGSCSM includes a test utility that can be used to verify the integrity of an