diff --git a/.github/workflows/build_workflow.yml b/.github/workflows/build_workflow.yml new file mode 100644 index 000000000..2e6006a40 --- /dev/null +++ b/.github/workflows/build_workflow.yml @@ -0,0 +1,83 @@ +name: CI/CD Build Workflow + +on: + push: + branches: + - master + + pull_request: + branches: + - master + + workflow_dispatch: + +env: + CANCEL_OTHERS: false + PATHS_IGNORE: '["**/README.md", "**/docs/**"]' + +jobs: + build: + name: test mpas_tools - python ${{ matrix.python-version }} + runs-on: ubuntu-latest + timeout-minutes: 20 + defaults: + run: + shell: bash -l {0} + strategy: + matrix: + python-version: ["3.9", "3.10", "3.11", "3.12"] + steps: + - id: skip_check + uses: fkirc/skip-duplicate-actions@master + with: + cancel_others: ${{ env.CANCEL_OTHERS }} + paths_ignore: ${{ env.PATHS_IGNORE }} + + - if: ${{ steps.skip_check.outputs.should_skip != 'true' }} + uses: actions/checkout@v4 + + - if: ${{ steps.skip_check.outputs.should_skip != 'true' }} + name: Cache Conda + uses: actions/cache@v4 + env: + # Increase this value to reset cache if dev-spec and setup.py have not changed in the workflow + CACHE_NUMBER: 0 + with: + path: ~/conda_pkgs_dir + key: + ${{ runner.os }}-${{ matrix.python-version }}-conda-${{ env.CACHE_NUMBER }}-${{ + hashFiles('conda_package/dev-spec.txt,conda_package/setup.py') }} + + - if: ${{ steps.skip_check.outputs.should_skip != 'true' }} + name: Create Build Environment + uses: conda-incubator/setup-miniconda@v3 + with: + activate-environment: "build" + miniforge-version: latest + channels: conda-forge + channel-priority: strict + auto-update-conda: true + python-version: ${{ matrix.python-version }} + + - if: ${{ steps.skip_check.outputs.should_skip != 'true' }} + name: Finalize Build Environment + run: | + conda install conda conda-build + conda build -m "conda_package/ci/linux_64_python${{ matrix.python-version }}.____cpython.yaml" "conda_package/recipe" + + - if: ${{ steps.skip_check.outputs.should_skip != 'true' }} + name: Install mpas_tools + run: | + conda create -y -n mpas_tools_dev --use-local mpas_tools \ + python=${{ matrix.python-version }} \ + sphinx sphinx-multiversion mock sphinx_rtd_theme + + - if: ${{ steps.skip_check.outputs.should_skip != 'true' }} + name: Build Sphinx Docs + run: | + conda activate mpas_tools_dev + # sphinx-multiversion expects at least a "master" branch + git branch master || echo "branch master already exists." + cd conda_package/docs + sphinx-multiversion . _build/html + diff --git a/.github/workflows/docs_workflow.yml b/.github/workflows/docs_workflow.yml new file mode 100644 index 000000000..01086202b --- /dev/null +++ b/.github/workflows/docs_workflow.yml @@ -0,0 +1,90 @@ +name: CI/CD Release Workflow + +on: + push: + branches: + - master + + release: + types: [published] + +jobs: + publish-docs: + runs-on: ubuntu-latest + defaults: + run: + shell: bash -l {0} + timeout-minutes: 20 + steps: + - uses: actions/checkout@v4 + with: + persist-credentials: false + fetch-depth: 0 + + - name: Cache Conda + uses: actions/cache@v4 + env: + # Increase this value to reset cache if dev-spec and setup.py have not changed in the workflow + CACHE_NUMBER: 0 + with: + path: ~/conda_pkgs_dir + key: ${{ runner.os }}-conda-${{ env.CACHE_NUMBER }}-${{ + hashFiles('conda_package/dev-spec.txt,conda_package/setup.py') }} + + - if: ${{ steps.skip_check.outputs.should_skip != 'true' }} + name: Set up Conda Environment + uses: conda-incubator/setup-miniconda@v3 + with: + activate-environment: "mpas_tools_ci" + miniforge-version: latest + channels: conda-forge + channel-priority: strict + auto-update-conda: true + python-version: ${{ matrix.python-version }} + + - if: ${{ steps.skip_check.outputs.should_skip != 'true' }} + name: Install mpas_tools + run: | + git config --global url."https://github.com/".insteadOf "git@github.com:" + conda create -n mpas_tools_dev --file conda_package/dev-spec.txt + conda activate mpas_tools_dev + python -m pip install -vv --no-deps --no-build-isolation -e conda_package + + - name: Build Sphinx Docs + run: | + set -e + cd conda_package/docs + conda activate mpas_tools_dev + sphinx-multiversion . _build/html + - name: Copy Docs and Commit + run: | + set -e + cd conda_package/docs + conda activate mpas_tools_dev + # gh-pages branch must already exist + git clone https://github.com/MPAS-Dev/MPAS-Tools.git --branch gh-pages --single-branch gh-pages + # Make sure we're in the gh-pages directory. + cd gh-pages + # Create `.nojekyll` (if it doesn't already exist) for proper GH Pages configuration. + touch .nojekyll + # Add `index.html` to point to the `master` branch automatically. + printf '' > index.html + # Only replace docs in a directory with the destination branch name with latest changes. Docs for + # releases should be untouched. + rm -rf ${{ github.head_ref || github.ref_name }} + # don't clobber existing release versions (in case we retroactively fixed them) + cp -r -n ../_build/html/* . + # Configure git using GitHub Actions credentials. + git config --local user.email "41898282+github-actions[bot]@users.noreply.github.com" + git config --local user.name "github-actions[bot]" + # The second command will fail if no changes were present, so we ignore it + git add . + git commit -m "Update documentation" -a || true + - name: Push Changes + uses: ad-m/github-push-action@master + with: + branch: gh-pages + directory: docs/gh-pages + github_token: ${{ secrets.GITHUB_TOKEN }} + force: true + diff --git a/azure-pipelines.yml b/azure-pipelines.yml deleted file mode 100644 index 8c244feba..000000000 --- a/azure-pipelines.yml +++ /dev/null @@ -1,180 +0,0 @@ -trigger: - branches: - include: - - master - tags: - include: - - '*' - -pr: - branches: - include: - - master - -jobs: -- job: - displayName: linux - pool: - vmImage: 'ubuntu-latest' - strategy: - matrix: - Python39: - python.version: '3.9' - Python310: - python.version: '3.10' - Python311: - python.version: '3.11' - Python312: - python.version: '3.12' - - steps: - - bash: echo "##vso[task.prependpath]$CONDA/bin" - displayName: Add conda to PATH - - - bash: | - conda config --add channels conda-forge - conda config --set channel_priority strict - conda create --yes --quiet --name build python=$PYTHON_VERSION conda conda-build - displayName: Create Anaconda build environment - - - bash: | - eval "$(conda shell.bash hook)" - conda activate build - conda build -m "conda_package/ci/linux_64_python${PYTHON_VERSION}.____cpython.yaml" "conda_package/recipe" - displayName: Build MPAS-Tools - - - bash: | - eval "$(conda shell.bash hook)" - conda activate build - conda create --yes --quiet --name test -c ${CONDA_PREFIX}/conda-bld/ \ - python=$PYTHON_VERSION mpas_tools pytest - displayName: Create Anaconda test environment - - - bash: | - eval "$(conda shell.bash hook)" - conda activate test - pytest --pyargs mpas_tools - displayName: pytest - - - bash: | - eval "$(conda shell.bash hook)" - conda activate build - conda create --yes --quiet --name docs -c ${CONDA_PREFIX}/conda-bld/ \ - python=$PYTHON_VERSION mpas_tools sphinx mock sphinx_rtd_theme m2r - condition: eq(variables['python.version'], '3.9') - displayName: Create Anaconda docs environment - - - bash: | - - # error out when something goes wrong - set -e - - eval "$(conda shell.bash hook)" - conda activate docs - - echo "source branch: $(Build.SourceBranch)" - echo "target branch: $(System.PullRequest.TargetBranch)" - echo "repository: $(Build.Repository.Name)" - - tag=$(git describe --tags $(git rev-list --tags --max-count=1)) - echo "tag: $tag" - - version=`python -c "import mpas_tools; print(mpas_tools.__version__)"` - echo "version: $version" - - REPO_PATH=$PWD - - if [[ "$(Build.SourceBranch)" == "refs/heads/master" ]]; then - export DOCS_VERSION="stable" - deploy=True - elif [[ "$(Build.SourceBranch)" == refs/tags/* ]]; then - # this is a tag build - export DOCS_VERSION="$tag" - deploy=True - else - DOCS_VERSION="$version" - export DOCS_VERSION - deploy=False - fi - echo "Docs version: $DOCS_VERSION" - echo "Deploy to gh-pages? $deploy" - cd conda_package/docs || exit 1 - make html - - cd "$REPO_PATH" || exit 1 - - if [[ "$deploy" == "True" ]]; then - PUBLICATION_BRANCH=gh-pages - # Checkout the branch - pushd $HOME || exit 1 - git clone --branch=$PUBLICATION_BRANCH https://$(GitHubToken)@github.com/$(Build.Repository.Name) publish - cd publish || exit 1 - - # Update pages - if [[ -d "$DOCS_VERSION" ]]; then - git rm -rf "$DOCS_VERSION" > /dev/null - fi - mkdir "$DOCS_VERSION" - cp -r "$REPO_PATH"/conda_package/docs/_build/html/* "$DOCS_VERSION" - # Commit and push latest version - git add . - if git diff-index --quiet HEAD; then - echo "No changes in the docs." - else - git config --local user.name "Azure Pipelines" - git config --local user.email "azuredevops@microsoft.com" - git commit -m "[skip ci] Update $DOCS_VERSION" - git push -fq origin $PUBLICATION_BRANCH - fi - popd || exit 1 - fi - condition: eq(variables['python.version'], '3.9') - displayName: build and deploy docs - -- job: - displayName: osx - pool: - vmImage: 'macOS-latest' - strategy: - matrix: - Python39: - python.version: '3.9' - Python310: - python.version: '3.10' - Python311: - python.version: '3.11' - Python312: - python.version: '3.12' - - steps: - - bash: echo "##vso[task.prependpath]$CONDA/bin" - displayName: Add conda to PATH - - - bash: sudo chown -R 501:20 /usr/local/miniconda/pkgs - displayName: Fix permissions - - - bash: | - conda config --add channels conda-forge - conda config --set channel_priority strict - conda create --yes --quiet --name build python=$PYTHON_VERSION conda conda-build - displayName: Create Anaconda build environment - - - bash: | - eval "$(conda shell.bash hook)" - conda activate build - conda build -m "conda_package/ci/osx_64_python${PYTHON_VERSION}.____cpython.yaml" "conda_package/recipe" - displayName: Build MPAS-Tools - - - bash: | - eval "$(conda shell.bash hook)" - conda activate build - conda create --yes --quiet --name test -c ${CONDA_PREFIX}/conda-bld/ \ - python=$PYTHON_VERSION mpas_tools pytest - displayName: Create Anaconda test environment - - - bash: | - eval "$(conda shell.bash hook)" - conda activate test - pytest --pyargs mpas_tools - displayName: pytest - diff --git a/conda_package/dev-spec.txt b/conda_package/dev-spec.txt index 046bf9dd4..1c6fca51b 100644 --- a/conda_package/dev-spec.txt +++ b/conda_package/dev-spec.txt @@ -31,5 +31,6 @@ pytest # Documentation sphinx +sphinx-multiversion mock sphinx_rtd_theme diff --git a/conda_package/docs/_static/style.css b/conda_package/docs/_static/style.css new file mode 100644 index 000000000..6cbfde333 --- /dev/null +++ b/conda_package/docs/_static/style.css @@ -0,0 +1,4 @@ +.wy-nav-content { + max-width: 1200px !important; +} + diff --git a/conda_package/docs/_templates/layout.html b/conda_package/docs/_templates/layout.html new file mode 100644 index 000000000..efc29758f --- /dev/null +++ b/conda_package/docs/_templates/layout.html @@ -0,0 +1,5 @@ +{% extends "!layout.html" %} +{% block extrahead %} + +{% endblock %} + diff --git a/conda_package/docs/_templates/versions.html b/conda_package/docs/_templates/versions.html new file mode 100644 index 000000000..625a9a384 --- /dev/null +++ b/conda_package/docs/_templates/versions.html @@ -0,0 +1,28 @@ +{%- if current_version %} +
+ + Other Versions + v: {{ current_version.name }} + + +
+ {%- if versions.tags %} +
+
Tags
+ {%- for item in versions.tags %} +
{{ item.name }}
+ {%- endfor %} +
+ {%- endif %} + {%- if versions.branches %} +
+
Branches
+ {%- for item in versions.branches %} +
{{ item.name }}
+ {%- endfor %} +
+ {%- endif %} +
+
+{%- endif %} + diff --git a/conda_package/docs/conf.py b/conda_package/docs/conf.py index 8cf4a6bbd..5d5e67ded 100644 --- a/conda_package/docs/conf.py +++ b/conda_package/docs/conf.py @@ -13,6 +13,8 @@ # serve to show the default. import os +from datetime import date + import mpas_tools # -- General configuration ------------------------------------------------ @@ -24,7 +26,9 @@ # Add any Sphinx extension module names here, as strings. They can be # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom # ones. -extensions = ['sphinx.ext.autodoc', +extensions = ['sphinx_rtd_theme', + 'sphinx_multiversion', + 'sphinx.ext.autodoc', 'sphinx.ext.autosummary', 'sphinx.ext.intersphinx', 'sphinx.ext.mathjax', @@ -55,14 +59,14 @@ master_doc = 'index' # General information about the project. -project = u'mpas_tools' -copyright = u'This software is open source software available under the BSD-3' \ - u'license. Copyright (c) 2019 Triad National Security, LLC. ' \ - u'All rights reserved. Copyright (c) 2019 Lawrence Livermore ' \ - u'National Security, LLC. All rights reserved. Copyright (c) ' \ - u'2019 UT-Battelle, LLC. All rights reserved.' -author = u'Xylar Asay-Davis, Doug Jacobsen, Michael Duda, Mark Petersen, ' \ - u'Matt Hoffman, Adridan Turner, Philip Wolfram' +project = 'mpas_tools' +year = date.today().year +copyright = f'This software is open source software available under the BSD-3' \ + f'license. Copyright (c) {year} Triad National Security, LLC. ' \ + f'All rights reserved. Copyright (c) {year} Lawrence Livermore ' \ + f'National Security, LLC. All rights reserved. Copyright (c) ' \ + f'{year} UT-Battelle, LLC. All rights reserved.' +author = 'MPAS-Tools development team' # The version info for the project you're documenting, acts as replacement for # |version| and |release|, also used in various other places throughout the @@ -102,14 +106,7 @@ # a list of builtin themes. # -# on_rtd is whether we are on readthedocs.org, this line of code grabbed from -# docs.readthedocs.org -on_rtd = os.environ.get('READTHEDOCS', None) == 'True' - -if not on_rtd: # only import and set the theme if we're building docs locally - import sphinx_rtd_theme - html_theme = 'sphinx_rtd_theme' - html_theme_path = [sphinx_rtd_theme.get_html_theme_path()] +html_theme = 'sphinx_rtd_theme' # Theme options are theme-specific and customize the look and feel of a theme # further. For a list of options available for each theme, see the @@ -185,6 +182,23 @@ 'numpy': ('http://docs.scipy.org/doc/numpy/', None), 'xarray': ('http://xarray.pydata.org/en/stable/', None), 'geometric_features': - ('http://mpas-dev.github.io/geometric_features/stable/', None)} + ('http://mpas-dev.github.io/geometric_features/main/', None)} github_doc_root = 'https://github.com/rtfd/recommonmark/tree/master/doc/' + +# 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_sidebars = { + "**": [ + "versions.html", + ], +} + +# -- Options sphinx-multiversion ------------------------------------------- +# Include tags like "tags/1.0.0" -- 0.0.1, 0.0.10 don't build +smv_tag_whitelist = r'^(?!(0.0.1|0.0.10))\d+\.\d+.\d+$' +smv_branch_whitelist = 'master' +smv_remote_whitelist = 'origin'