diff --git a/.github/jobs/build_documentation.sh b/.github/jobs/build_documentation.sh new file mode 100755 index 0000000..95f0596 --- /dev/null +++ b/.github/jobs/build_documentation.sh @@ -0,0 +1,30 @@ +#! /bin/bash + +# path to docs directory relative to top level of repository +# $GITHUB_WORKSPACE is set if the actions/checkout@v4 action is run first + +DOCS_DIR=${GITHUB_WORKSPACE}/docs + +if [ ! -e ${DOCS_DIR} ]; then + echo "Documentation directory does not exist: ${DOCS_DIR}" + exit 1 +fi + +# run Make to build the documentation and return to previous directory +cd ${DOCS_DIR} +make clean html +cd - + +# copy HTML output into directory to create an artifact +mkdir -p artifact/documentation +cp -r ${DOCS_DIR}/_build/html/* artifact/documentation + +# check if the warnings.log file is empty +# Copy it into the artifact and documentation directories +# so it will be available in the artifacts +warning_file=${DOCS_DIR}/_build/warnings.log +if [ -s $warning_file ]; then + cp -r ${DOCS_DIR}/_build/warnings.log artifact/doc_warnings.log + cp artifact/doc_warnings.log artifact/documentation + exit 1 +fi diff --git a/.github/workflows/documentation.yml b/.github/workflows/documentation.yml new file mode 100644 index 0000000..cc05ecd --- /dev/null +++ b/.github/workflows/documentation.yml @@ -0,0 +1,41 @@ +name: Documentation +on: + push: + branches: + - develop + - feature_* + - main* + - bugfix_* + paths: + - docs/** + pull_request: + types: [opened, reopened, synchronize] + workflow_dispatch: + +jobs: + documentation: + name: Build Documentation + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + - uses: actions/setup-python@v5 + with: + python-version: '3.8' + - name: Install dependencies + run: | + python -m pip install --upgrade python-dateutil requests sphinx \ + sphinx-gallery Pillow sphinx_rtd_theme sphinx-panels + python -m pip install -r docs/requirements.txt + - name: Build docs + run: ./.github/jobs/build_documentation.sh + - uses: actions/upload-artifact@v4 + if: always() + with: + name: documentation + path: artifact/documentation + - uses: actions/upload-artifact@v4 + if: failure() + with: + name: documentation_warnings.log + path: artifact/doc_warnings.log + if-no-files-found: ignore diff --git a/docs/Tutorial/introduction.rst b/docs/Tutorial/introduction.rst index bea898f..1bcd55f 100644 --- a/docs/Tutorial/introduction.rst +++ b/docs/Tutorial/introduction.rst @@ -1,5 +1,6 @@ +************ Introduction -============ +************ `FastEddy`_ is a resident-GPU large eddy simulation (LES) model owned by the National Center for Atmospheric Research (`NCAR`_) Research Applications Laboratory (`RAL`_). It is designed for future turbulence-resolving numerical weather prediction. diff --git a/docs/index.rst b/docs/index.rst index 20bd13c..f52b138 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -17,6 +17,6 @@ engineering applications. .. toctree:: :hidden: - :caption: FastEddy + :caption: TUTORIAL Tutorial/index