Unverified Commit f618d23c authored by acpaquette's avatar acpaquette Committed by GitHub
Browse files

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
parent ad2fef29

.github/workflows/aws_doc_deploy.yml

0 → 100644
+37 −0
Original line number Diff line number Diff line 
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

+36 −3
Original line number Diff line number Diff line
@@ -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

+12 −0
Original line number Diff line number Diff line 
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

+2 −2
Original line number Diff line number Diff line
@@ -4,8 +4,8 @@ channels: 
  - default



dependencies:

  - breathe

  - cmake>=3.12

  - ale

  - csm

  - doxygen

  - nlohmann_json
 
  - breathe

docs/CMakeLists.txt

0 → 100644
+65 −0
Original line number Diff line number Diff line 
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})