Docs workflow (#557)

* Docs workflow (#549)

* Test docs build

* Retry

* Add brackets

* Add conda install doxygen and doxygen command

* Output some logging

* Move doxygen command inside docs dir

* Fix ls typo

* Build docs for all linux

* Add back cd docs

* Test windows

* Try python3.11

* Conditional build docs

* Build docs on 3.11

* Test S3 connection

* Setup Hugo

* Add permissions

* Add condition to build docs when merging

* Add no-sign-request bool

* Replace aws ls with sync

* Try removing no-sign-request for sync

* Add back no-sign-request with existing ale folder in s3

* Try changing aws-region

* Change region back to west-2 and test only ls

* Upload to asc-docs instead of asc-public-docs

* Test selective build and docs upload

* Use sphinx-build cmd

* Revert and upload only html folder

* Full test run

* Set docs push condition to last two steps

* Change branch to main

* Update docs setup

* Update make.bat configs

* Turn off docs build for windows

* OCAP compliance

* Revert file structure

* Just in case windows too

* Fix sphinx doc folder path

* Remove public/.doctrees

.github/workflows/aws_doc_deploy.yml

+name: aws-doc-deploy
+
+on:
+  workflow_run:
+    workflows: ["Pull-Request-CI"]
+    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: conda-incubator/setup-miniconda@3b0f2504dd76ef23b6d31f291f4913fb60ab5ff3
+        with:
+          miniconda-version: "latest"
+          activate-environment: ale
+          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 . public
+            
+      - 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
+        run: aws s3 sync --delete public s3://asc-docs/ale

.github/workflows/ci_testing.yml

@@ -44,7 +44,7 @@ jobs:
         run: |
           mkdir -p build
           cd build
-          cmake -DCMAKE_BUILD_TYPE=RELEASE -DCOVERAGE=ON ..
+          cmake -DCMAKE_BUILD_TYPE=RELEASE -DCOVERAGE=ON -DALE_BUILD_DOCS=OFF ..
           cmake --build .
       - name: Test C++ Package
         run: |
@@ -58,6 +58,32 @@ jobs:
           verbose: true
         if: matrix.os == 'ubuntu-latest' && matrix.python-version == '3.9'
 
+  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: ale
+          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 . public
+
   Build-and-Test-Win:
     runs-on: windows-2019
     strategy:
@@ -82,7 +108,7 @@ jobs:
         run: |
           mkdir -p build
           cd build
-          cmake -DCMAKE_BUILD_TYPE=RELEASE -DCMAKE_WINDOWS_EXPORT_ALL_SYMBOLS=ON -G "Visual Studio 16 2019" -A x64 -DALE_BUILD_TESTS=OFF ..
+          cmake -DCMAKE_BUILD_TYPE=RELEASE -DCMAKE_WINDOWS_EXPORT_ALL_SYMBOLS=ON -G "Visual Studio 16 2019" -A x64 -DALE_BUILD_TESTS=OFF -DALE_BUILD_DOCS=OFF ..
           cmake --build . --target ALL_BUILD --config Release
           ls D:\a\ale\ale\build\Release
       - uses: actions/upload-artifact@0b7f8abb1508181956e8e162db84b466c27e18ce

CMakeLists.txt

@@ -9,6 +9,10 @@
 cmake_minimum_required(VERSION 3.15)
 project(ale VERSION 0.9.0 DESCRIPTION "Abstraction Library for Ephemerides ")
 
+list(APPEND CMAKE_MODULE_PATH "${CMAKE_CURRENT_SOURCE_DIR}/cmake")
+
+message(STATUS "CMake Module Path: " ${CMAKE_MODULE_PATH})
+
 # include what we need
 include(GNUInstallDirs)
 
@@ -131,3 +135,10 @@ install(TARGETS ale
 install(EXPORT aleTargets
         NAMESPACE ale::
         DESTINATION ${CMAKE_INSTALL_LIBDIR}/cmake/${PROJECT_NAME})
+
+option (ALE_BUILD_DOCS "Build the ALE Docs" ON)
+if(ALE_BUILD_DOCS)
+  add_subdirectory ("docs")
+else()
+  message(STATUS "Skipping Docs")
+endif()
\ No newline at end of file

cmake/FindSphinx.cmake

+#Look for an executable called sphinx-build
+find_program(SPHINX_EXECUTABLE
+             NAMES sphinx-build
+             DOC "Path to sphinx-build executable")
+
+include(FindPackageHandleStandardArgs)
+
+#Handle standard arguments to find_package like REQUIRED and QUIET
+find_package_handle_standard_args(Sphinx
+                                  "Failed to find sphinx-build executable"
+                                  SPHINX_EXECUTABLE)

doc_environment.yml

+name: ale
+channels:
+  - conda-forge
+  - default
+
+dependencies:
+  - breathe
+  - cmake>=3.12
+  - doxygen
+  - nlohmann_json
\ No newline at end of file

docs/CMakeLists.txt

+message(STATUS "Setting Up Docs")
+
+find_package(Doxygen REQUIRED)
+find_package(Sphinx REQUIRED)
+
+# Find all the public headers
+set(ALE_BUILD_INCLUDE_DIR "${CMAKE_CURRENT_SOURCE_DIR}/include/ale")
+file(GLOB_RECURSE ALE_PUBLIC_HEADERS ${ALE_BUILD_INCLUDE_DIR}/*.h)
+
+set(DOXYGEN_INPUT_DIR ${PROJECT_SOURCE_DIR}/ale/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 ${ALE_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})
+set(SPHINX_BUILD ${CMAKE_CURRENT_BINARY_DIR}/sphinx)
+set(SPHINX_INDEX_FILE ${SPHINX_BUILD}/index.html)
+
+set(SPHINX_RST_FILES ${CMAKE_CURRENT_SOURCE_DIR}/index.rst)
+
+add_custom_command(OUTPUT ${SPHINX_INDEX_FILE}
+                   COMMAND
+                     ${SPHINX_EXECUTABLE} -b html
+                     # Tell Breathe where to find the Doxygen output
+                     -Dbreathe_projects.Ale=${DOXYGEN_OUTPUT_DIR}/xml
+                   ${SPHINX_SOURCE} ${SPHINX_BUILD}
+                   WORKING_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}
+                   DEPENDS ${ALE_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/Doxyfile → docs/Doxyfile.in

@@ -58,7 +58,7 @@ PROJECT_LOGO           =
 # entered, it will be relative to the location where doxygen was started. If
 # left blank the current directory will be used.
 
-OUTPUT_DIRECTORY       =./
+OUTPUT_DIRECTORY       =
 
 # If the CREATE_SUBDIRS tag is set to YES then doxygen will create 4096 sub-
 # directories (in 2 levels) under the output directory of each output format and
@@ -791,7 +791,7 @@ WARN_LOGFILE           =
 # spaces. See also FILE_PATTERNS and EXTENSION_MAPPING
 # Note: If this tag is empty the current directory is searched.
 
-INPUT                  = ../include/ale/ ./ale 
+INPUT                  = ../src/ ../include/ale/
 
 # This tag can be used to specify the character encoding of the source files
 # that doxygen parses. Internally doxygen uses the UTF-8 encoding. Doxygen uses
@@ -1944,7 +1944,7 @@ GENERATE_XML           = YES
 # The default directory is: xml.
 # This tag requires that the tag GENERATE_XML is set to YES.
 
-XML_OUTPUT             = doxyxml
+XML_OUTPUT             = xml
 
 # If the XML_PROGRAMLISTING tag is set to YES, doxygen will dump the program
 # listings (including syntax highlighting and cross-referencing information) to

docs/Makefile

-# Minimal makefile for Sphinx documentation
-#
-
-# You can set these variables from the command line.
-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)
\ No newline at end of file

docs/_templates/layout.html

+{% extends '!layout.html' %}
+
+{% block header %}
+    {% include "usgsheader.html" %}
+    {{ super() }}
+{% endblock %}
+
+{% block footer %}
+    {% include "usgsfooter.html" %}
+{% endblock %}

docs/_templates/usgsfooter.html

+<footer class="footer">
+    <div class="tmp-container">
+      
+        
+        <div class="footer-doi">
+          
+          <ul class="menu nav">
+            <li class="first leaf menu-links menu-level-1"><a href="https://www.doi.gov/privacy">DOI Privacy Policy</a></li>
+            <li class="leaf menu-links menu-level-1"><a href="https://www.usgs.gov/policies-and-notices">Legal</a></li>
+            <li class="leaf menu-links menu-level-1"><a href="https://www.usgs.gov/accessibility-and-us-geological-survey">Accessibility</a></li>
+            <li class="leaf menu-links menu-level-1"><a href="https://www.usgs.gov/sitemap">Site Map</a></li>
+            <li class="last leaf menu-links menu-level-1"><a href="https://answers.usgs.gov/">Contact USGS</a></li>
+          </ul>
+                
+        </div> 
+        <hr>
+  
+      
+      <div class="footer-doi">
+        <ul class="menu nav">
+          <li class="first leaf menu-links menu-level-1"><a href="https://www.doi.gov/">U.S. Department of the Interior</a></li>
+          <li class="leaf menu-links menu-level-1"><a href="https://www.doioig.gov/">DOI Inspector General</a></li>
+          <li class="leaf menu-links menu-level-1"><a href="https://www.whitehouse.gov/">White House</a></li>
+          <li class="leaf menu-links menu-level-1"><a href="https://www.whitehouse.gov/omb/management/egov/">E-gov</a></li>
+          <li class="leaf menu-links menu-level-1"><a href="https://www.doi.gov/pmb/eeo/no-fear-act">No Fear Act</a></li>
+          <li class="last leaf menu-links menu-level-1"><a href="https://www.usgs.gov/about/organization/science-support/foia">FOIA</a></li>
+        </ul>
+        </div>			
+      
+      
+      <div class="footer-social-links">
+        <ul class="social">
+          <li class="follow">Follow</li>
+          <li class="twitter">
+            <a href="https://twitter.com/usgs" target="_blank">
+              <i class="fa fa-twitter-square"><span class="only">Twitter</span></i>
+            </a>
+          </li>
+          <li class="facebook">
+            <a href="https://facebook.com/usgeologicalsurvey" target="_blank">
+              <i class="fa fa-facebook-square"><span class="only">Facebook</span></i>
+            </a>
+          </li>
+          <li class="github">
+            <a href="https://github.com/usgs" target="_blank">
+              <i class="fa fa-github"><span class="only">GitHub</span></i>
+            </a>
+          </li>
+          <li class="flickr">
+            <a href="https://flickr.com/usgeologicalsurvey" target="_blank">
+              <i class="fa fa-flickr"><span class="only">Flickr</span></i>
+            </a>
+          </li>
+          <li class="youtube">
+            <a href="http://youtube.com/usgs" target="_blank">
+              <i class="fa fa-youtube-play"><span class="only">YouTube</span></i>
+            </a>
+          </li>
+          <li class="instagram">
+            <a href="https://instagram.com/usgs" target="_blank">
+              <i class="fa fa-instagram"><span class="only">Instagram</span></i>
+            </a>
+          </li>
+        </ul>
+      </div>
+      
+    </div>
+        
+  </footer>
+  
\ No newline at end of file

docs/_templates/usgsheader.html

+
+<link href="https://asc-public-docs.s3.us-west-2.amazonaws.com/common/uswds/3.6.0/css/common.css" rel="stylesheet" type="text/css" media="screen" />
+<link href="https://asc-public-docs.s3.us-west-2.amazonaws.com/common/uswds/3.6.0/css/custom.css" rel="stylesheet" type="text/css" media="screen" />   
+<link href="https://asc-public-docs.s3.us-west-2.amazonaws.com/common/uswds/3.6.0/css/uswds.min.css" rel="stylesheet" type="text/css" media="screen" /> 
+
+<script async type="text/javascript" src="https://dap.digitalgov.gov/Universal-Federated-Analytics-Min.js?agency=DOI" id="_fed_an_ua_tag"></script>
+
+<!DOCTYPE html>
+<html>
+  <head>
+    <meta charset="utf-8" />
+    <meta http-equiv="X-UA-Compatible" content="IE=edge" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <title>USGSCSM</title>
+  </head>
+  <body>
+    <script type="text/javascript" src="https://asc-public-docs.s3.us-west-2.amazonaws.com/common/uswds/3.6.0/js/uswds-init.min.js"></script>
+    <script type="text/javascript" src="https://asc-public-docs.s3.us-west-2.amazonaws.com/common/uswds/3.6.0/js/uswds.min.js"></script>
+  </body>
+</html>
+
+
+<section class="usa-banner" aria-label="Official government website">
+    <div class="usa-accordion">
+      <header class="usa-banner__header">
+        <div class="usa-banner__inner">
+          <div class="grid-col-auto">
+            <img
+              class="usa-banner__header-flag"
+              src="https://asc-public-docs.s3.us-west-2.amazonaws.com/common/uswds/3.6.0/img/us_flag_small.png"
+              alt="U.S. flag"
+            />
+          </div>
+          <div class="grid-col-fill tablet:grid-col-auto">
+            <p class="usa-banner__header-text">
+              An official website of the United States government
+            </p>
+            <p class="usa-banner__header-action" aria-hidden="true">
+              Here’s how you know
+            </p>
+          </div>
+          <button
+            type="button"
+            class="usa-accordion__button usa-banner__button"
+            aria-expanded="false"
+            aria-controls="gov-banner-default-default"
+          >
+            <span class="usa-banner__button-text">Here’s how you know</span>
+          </button>
+        </div>
+      </header>
+      <div
+        class="usa-banner__content usa-accordion__content"
+        id="gov-banner-default-default"
+      >
+        <div class="grid-row grid-gap-lg">
+          <div class="usa-banner__guidance tablet:grid-col-6">
+            <img
+              class="usa-banner__icon usa-media-block__img"
+              src="https://asc-public-docs.s3.us-west-2.amazonaws.com/common/uswds/3.6.0/img/icon-dot-gov.svg"
+              role="img"
+              alt=""
+              aria-hidden="true"
+            />
+            <div class="usa-media-block__body">
+              <p>
+                <strong>Official websites use .gov</strong><br />A
+                <strong>.gov</strong> website belongs to an official government
+                organization in the United States.
+              </p>
+            </div>
+          </div>
+          <div class="usa-banner__guidance tablet:grid-col-6">
+            <img
+              class="usa-banner__icon usa-media-block__img"
+              src="https://asc-public-docs.s3.us-west-2.amazonaws.com/common/uswds/3.6.0/img/icon-https.svg"
+              role="img"
+              alt=""
+              aria-hidden="true"
+            />
+            <div class="usa-media-block__body">
+              <p>
+                <strong>Secure .gov websites use HTTPS</strong><br />A
+                <strong>lock</strong> (
+                <span class="icon-lock"
+                  ><svg
+                    xmlns="http://www.w3.org/2000/svg"
+                    width="52"
+                    height="64"
+                    viewBox="0 0 52 64"
+                    class="usa-banner__lock-image"
+                    role="img"
+                    aria-labelledby="banner-lock-title-default banner-lock-description-default"
+                    focusable="false"
+                  >
+                    <title id="banner-lock-title-default">Lock</title>
+                    <desc id="banner-lock-description-default">A locked padlock</desc>
+                    <path
+                      fill="#000000"
+                      fill-rule="evenodd"
+                      d="M26 0c10.493 0 19 8.507 19 19v9h3a4 4 0 0 1 4 4v28a4 4 0 0 1-4 4H4a4 4 0 0 1-4-4V32a4 4 0 0 1 4-4h3v-9C7 8.507 15.507 0 26 0zm0 8c-5.979 0-10.843 4.77-10.996 10.712L15 19v9h22v-9c0-6.075-4.925-11-11-11z"
+                    />
+                  </svg> </span
+                >) or <strong>https://</strong> means you’ve safely connected to
+                the .gov website. Share sensitive information only on official,
+                secure websites.
+              </p>
+            </div>
+          </div>
+        </div>
+      </div>
+    </div>
+  </section>
+
+
+
+
+    <header id="navbar" class="header-nav"  role="banner">
+        <div class="tmp-container">
+            <div class="header-search">
+             <a class="logo-header" href="https://www.usgs.gov/" title="Home">
+                <img class="img"  src="https://asc-public-docs.s3.us-west-2.amazonaws.com/common/uswds/3.6.0/img/logo.png"  alt="Home" />
+              </a>
+              <form action="https://www.usgs.gov/science-explorer-results" method="GET" id="search-box">
+               <div class="fa-wrapper"><label for="se_search" class="only">Search</label>
+                <input id="se_search" type="search" name="es" placeholder="Search">
+                <button class="fa fa-search" type="submit">
+                  <span class="only">Search</span>
+                   </button></div>
+              </form>
+            </div>
+            
+          </div> 
+          
+      </header>
+

docs/conf.py

@@ -11,9 +11,9 @@
 # documentation root, use os.path.abspath to make it absolute, like shown here.
 #
 import os
-import sys
+# import sys
 import subprocess
-sys.path.insert(0, os.path.abspath('../ale'))
+# sys.path.insert(0, os.path.abspath('../ale'))
 
 
 # -- Project information -----------------------------------------------------
@@ -55,16 +55,17 @@ html_theme = 'alabaster'
 # 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']
+# html_static_path = ['_static']
+
 
 # -- Run Doxygen for C++ API --------------------------------------------------
 
 read_the_docs_build = os.environ.get('READTHEDOCS', None) == 'True'
 
 if read_the_docs_build:
-    subprocess.call('doxygen', shell=True)
+    subprocess.call('doxygen Doxyfile', shell=True)
     
 # -- Breathe Configuration ----------------------------------------------------
 
-breathe_projects = { "ALE": "doxyxml/" }
+breathe_projects = { "ALE": "xml/" }
 breathe_default_project = "ALE"

docs/make.bat

@@ -8,7 +8,7 @@ if "%SPHINXBUILD%" == "" (
 	set SPHINXBUILD=sphinx-build
 )
 set SOURCEDIR=.
-set BUILDDIR=_build
+set BUILDDIR=build
 
 if "%1" == "" goto help