From ab6cbd4e2563c97d0f2a87c1a3dc5e639c9e545c Mon Sep 17 00:00:00 2001 From: Althea Denlinger Date: Wed, 30 Oct 2024 09:35:39 -0700 Subject: [PATCH 1/8] Remove old azure pipelines config --- azure-pipelines.yml | 180 -------------------------------------------- 1 file changed, 180 deletions(-) delete mode 100644 azure-pipelines.yml 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 - From 5cfe0e535fa5c739823bfe2d127af239cdf1202b Mon Sep 17 00:00:00 2001 From: Althea Denlinger Date: Wed, 30 Oct 2024 09:50:50 -0700 Subject: [PATCH 2/8] Add build workflow --- .github/workflows/build_workflow.yml | 85 ++++++++++++++++++++++++++++ 1 file changed, 85 insertions(+) create mode 100644 .github/workflows/build_workflow.yml diff --git a/.github/workflows/build_workflow.yml b/.github/workflows/build_workflow.yml new file mode 100644 index 000000000..fa0c945f3 --- /dev/null +++ b/.github/workflows/build_workflow.yml @@ -0,0 +1,85 @@ +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: | + cd conda_package + conda create -n mpas_tools_dev --file dev-spec.txt \ + python=${{ matrix.python-version }} + conda activate mpas_tools_dev + python -m pip install --no-deps --no-build-isolation -vv -e . + + - 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 + From cdcb15c0b9e9c7697083448e073c872ab842fce7 Mon Sep 17 00:00:00 2001 From: Althea Denlinger Date: Wed, 30 Oct 2024 09:54:25 -0700 Subject: [PATCH 3/8] Add docs workflow --- .github/workflows/docs_workflow.yml | 91 +++++++++++++++++++++++++++++ 1 file changed, 91 insertions(+) create mode 100644 .github/workflows/docs_workflow.yml diff --git a/.github/workflows/docs_workflow.yml b/.github/workflows/docs_workflow.yml new file mode 100644 index 000000000..62b95e2c7 --- /dev/null +++ b/.github/workflows/docs_workflow.yml @@ -0,0 +1,91 @@ +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: | + cd conda_package + git config --global url."https://github.com/".insteadOf "git@github.com:" + conda create -n mpas_tools_dev --file dev-spec.txt + conda activate mpas_tools_dev + python -m pip install -vv --no-deps --no-build-isolation -e . + + - 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 + From eec946f602c42ae8b2f9e2b1f161068e550c8dd9 Mon Sep 17 00:00:00 2001 From: Althea Denlinger Date: Wed, 30 Oct 2024 09:56:41 -0700 Subject: [PATCH 4/8] Add sphinx-multiversion package --- conda_package/dev-spec.txt | 1 + 1 file changed, 1 insertion(+) 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 From 26c0624d3aa360d4d8edc1fdcf4d322ca74e5784 Mon Sep 17 00:00:00 2001 From: Xylar Asay-Davis Date: Wed, 6 Nov 2024 07:09:08 +0100 Subject: [PATCH 5/8] Update docs config --- conda_package/docs/conf.py | 50 ++++++++++++++++++++++++-------------- 1 file changed, 32 insertions(+), 18 deletions(-) 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' From 1f59352668f2c4f5cb48e95669bc6c36ff0b3d00 Mon Sep 17 00:00:00 2001 From: Xylar Asay-Davis Date: Wed, 6 Nov 2024 00:10:43 -0600 Subject: [PATCH 6/8] Add files needed to get multiversion side bar to work --- conda_package/docs/_static/style.css | 4 +++ conda_package/docs/_templates/layout.html | 5 ++++ conda_package/docs/_templates/versions.html | 28 +++++++++++++++++++++ 3 files changed, 37 insertions(+) create mode 100644 conda_package/docs/_static/style.css create mode 100644 conda_package/docs/_templates/layout.html create mode 100644 conda_package/docs/_templates/versions.html 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 %} + From 62029a9791087e469813d53d3532543de7595c44 Mon Sep 17 00:00:00 2001 From: Xylar Asay-Davis Date: Wed, 6 Nov 2024 15:43:52 +0100 Subject: [PATCH 7/8] Fix package install on CI --- .github/workflows/build_workflow.yml | 8 +++----- 1 file changed, 3 insertions(+), 5 deletions(-) diff --git a/.github/workflows/build_workflow.yml b/.github/workflows/build_workflow.yml index fa0c945f3..2e6006a40 100644 --- a/.github/workflows/build_workflow.yml +++ b/.github/workflows/build_workflow.yml @@ -68,11 +68,9 @@ jobs: - if: ${{ steps.skip_check.outputs.should_skip != 'true' }} name: Install mpas_tools run: | - cd conda_package - conda create -n mpas_tools_dev --file dev-spec.txt \ - python=${{ matrix.python-version }} - conda activate mpas_tools_dev - python -m pip install --no-deps --no-build-isolation -vv -e . + 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 From 6bbd4b961388af1e40191385939db0abad4d1bf1 Mon Sep 17 00:00:00 2001 From: Xylar Asay-Davis Date: Wed, 6 Nov 2024 16:19:49 +0100 Subject: [PATCH 8/8] Switch to safer workflow for creating docs environment --- .github/workflows/docs_workflow.yml | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/.github/workflows/docs_workflow.yml b/.github/workflows/docs_workflow.yml index 62b95e2c7..01086202b 100644 --- a/.github/workflows/docs_workflow.yml +++ b/.github/workflows/docs_workflow.yml @@ -45,11 +45,10 @@ jobs: - if: ${{ steps.skip_check.outputs.should_skip != 'true' }} name: Install mpas_tools run: | - cd conda_package git config --global url."https://github.com/".insteadOf "git@github.com:" - conda create -n mpas_tools_dev --file dev-spec.txt + 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 . + python -m pip install -vv --no-deps --no-build-isolation -e conda_package - name: Build Sphinx Docs run: |