diff --git a/.github/workflows/build_workflow.yml b/.github/workflows/build_workflow.yml new file mode 100644 index 00000000..96d6e526 --- /dev/null +++ b/.github/workflows/build_workflow.yml @@ -0,0 +1,97 @@ +name: CI/CD Build Workflow + +on: + push: + branches: + - main + + pull_request: + branches: + - main + + workflow_dispatch: + +env: + CANCEL_OTHERS: false + PATHS_IGNORE: '["**/README.md", "**/docs/**"]' + +jobs: + build: + name: test geometric_features - 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 conda-dev-spec.template has not changed in the workflow + CACHE_NUMBER: 0 + with: + path: ~/conda_pkgs_dir + key: + ${{ runner.os }}-${{ matrix.python-version }}-conda-${{ env.CACHE_NUMBER }}-${{ + hashFiles('dev-spec.txt,setup.py') }} + + - if: ${{ steps.skip_check.outputs.should_skip != 'true' }} + name: Set up Conda Environment + uses: conda-incubator/setup-miniconda@v3 + with: + activate-environment: "geometric_features_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 geometric_features + run: | + conda create -n geometric_features_dev --file dev-spec.txt \ + python=${{ matrix.python-version }} + conda activate geometric_features_dev + python -m pip install --no-deps --no-build-isolation -vv -e . + + - if: ${{ steps.skip_check.outputs.should_skip != 'true' }} + name: Run Tests + env: + CHECK_IMAGES: False + run: | + set -e + conda activate geometric_features_dev + pip check + pytest --pyargs geometric_features + combine_features -v + difference_features -v + fix_features_at_antimeridian -v + merge_features -v + plot_features -v + set_group_name -v + simplify_features -v + split_features -v + tag_features -v + + - if: ${{ steps.skip_check.outputs.should_skip != 'true' }} + name: Build Sphinx Docs + run: | + conda activate geometric_features_dev + # sphinx-multiversion expects at least a "main" branch + git branch main || echo "branch main already exists." + cd docs + sphinx-multiversion . _build/html + diff --git a/.github/workflows/docs_workflow.yml b/.github/workflows/docs_workflow.yml new file mode 100644 index 00000000..9b795a6c --- /dev/null +++ b/.github/workflows/docs_workflow.yml @@ -0,0 +1,93 @@ +name: CI/CD Release Workflow + +on: + push: + branches: + - main + + 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 deploy/conda-dev-spec.template has not changed in the workflow + CACHE_NUMBER: 0 + with: + path: ~/conda_pkgs_dir + key: ${{ runner.os }}-conda-${{ env.CACHE_NUMBER }}-${{ + hashFiles('dev-spec.txt') }} + + - if: ${{ steps.skip_check.outputs.should_skip != 'true' }} + name: Set up Conda Environment + uses: conda-incubator/setup-miniconda@v3 + with: + activate-environment: "geometric_features_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 geometric_features + run: | + git config --global url."https://github.com/".insteadOf "git@github.com:" + conda create -n geometric_features_dev --file dev-spec.txt \ + python=${{ matrix.python-version }} + conda activate geometric_features_dev + python -m pip install -vv --no-deps --no-build-isolation -e . + + - name: Build Sphinx Docs + run: | + set -e + conda activate geometric_features_dev + pip check + cd docs + sphinx-multiversion . _build/html + - name: Copy Docs and Commit + run: | + set -e + conda activate geometric_features_dev + pip check + cd docs + # gh-pages branch must already exist + git clone https://github.com/MPAS-Dev/geometric_features.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 `main` 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/README.md b/README.md index 0c29045e..7c27585e 100644 --- a/README.md +++ b/README.md @@ -1,7 +1,3 @@ -# Geometric Features - -[![Build Status](https://dev.azure.com/MPAS-Dev/geometric_features%20testing/_apis/build/status/MPAS-Dev.geometric_features?branchName=main)](https://dev.azure.com/MPAS-Dev/geometric_features%20testing/_build/latest?definitionId=3&branchName=main) - This repository houses definitions of geometric features. These features can include regions, transects, and points, described in geojson format. For example, here are some regions for Antarctica. @@ -9,7 +5,7 @@ For example, here are some regions for Antarctica. ## Documentation -[http://mpas-dev.github.io/geometric_features/stable/](http://mpas-dev.github.io/geometric_features/stable/) +[http://mpas-dev.github.io/geometric_features/main/](http://mpas-dev.github.io/geometric_features/main/) ## Contributors diff --git a/azure-pipelines.yml b/azure-pipelines.yml deleted file mode 100644 index 03e03a86..00000000 --- a/azure-pipelines.yml +++ /dev/null @@ -1,118 +0,0 @@ -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: | - set -e - eval "$(conda shell.bash hook)" - conda config --add channels conda-forge - conda config --set channel_priority strict - conda update --yes --all - conda install --yes mamba - # workaround based on recent failures - rm /usr/share/miniconda/pkgs/cache/*.json - mamba install --yes conda-build boa - displayName: Update conda base environment - - - bash: | - set -e - eval "$(conda shell.bash hook)" - # workaround based on recent failures - rm /usr/share/miniconda/pkgs/cache/*.json - conda mambabuild -m "ci/python${PYTHON_VERSION}.yaml" "recipe" - displayName: Build geometric_features - - - bash: | - set -e - eval "$(conda shell.bash hook)" - mamba create --yes --quiet --name test -c ${CONDA_PREFIX}/conda-bld/ \ - python=$PYTHON_VERSION geometric_features pytest sphinx mock \ - sphinx_rtd_theme m2r2 - displayName: Create Anaconda test environment - - - bash: | - set -e - eval "$(conda shell.bash hook)" - conda activate test - pytest --pyargs geometric_features - displayName: pytest - - - bash: | - set -e - eval "$(conda shell.bash hook)" - conda activate test - - 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 geometric_features; print(geometric_features.__version__)"` - echo "version: $version" - - REPO_PATH=$PWD - - if [[ "$(Build.SourceBranch)" == "refs/heads/main" ]]; 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 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"/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.10') - displayName: build and deploy docs diff --git a/dev-spec.txt b/dev-spec.txt index 86e841f8..0aa903c4 100644 --- a/dev-spec.txt +++ b/dev-spec.txt @@ -18,4 +18,5 @@ pytest # Documentation sphinx sphinx_rtd_theme +sphinx-multiversion m2r2 diff --git a/docs/_static/style.css b/docs/_static/style.css new file mode 100644 index 00000000..6cbfde33 --- /dev/null +++ b/docs/_static/style.css @@ -0,0 +1,4 @@ +.wy-nav-content { + max-width: 1200px !important; +} + diff --git a/docs/_templates/layout.html b/docs/_templates/layout.html new file mode 100644 index 00000000..efc29758 --- /dev/null +++ b/docs/_templates/layout.html @@ -0,0 +1,5 @@ +{% extends "!layout.html" %} +{% block extrahead %} + +{% endblock %} + diff --git a/docs/_templates/versions.html b/docs/_templates/versions.html new file mode 100644 index 00000000..625a9a38 --- /dev/null +++ b/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/docs/conf.py b/docs/conf.py index bc0285de..936bdf58 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -13,6 +13,8 @@ # serve to show the default. import os +from datetime import date + import geometric_features from geometric_features.docs.parse_quick_start import build_quick_start @@ -25,12 +27,16 @@ # 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', - 'sphinx.ext.autosummary', - 'sphinx.ext.intersphinx', - 'sphinx.ext.mathjax', - 'sphinx.ext.viewcode', - 'sphinx.ext.napoleon'] +extensions = [ + 'sphinx_rtd_theme', + 'sphinx_multiversion', + 'sphinx.ext.autodoc', + 'sphinx.ext.autosummary', + 'sphinx.ext.intersphinx', + 'sphinx.ext.mathjax', + 'sphinx.ext.viewcode', + 'sphinx.ext.napoleon' +] autosummary_generate = True @@ -53,13 +59,13 @@ master_doc = 'index' # General information about the project. -project = u'geometric_features' -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) 2018 Lawrence Livermore ' \ - u'National Security, LLC. All rights reserved. Copyright (c) ' \ - u'2018 UT-Battelle, LLC. All rights reserved.' -author = u'Xylar Asay-Davis, Doug Jacobsen, Phillip Wolfram' +project = 'geometric_features' +copyright = f'This software is open source software available under the BSD-3' \ + f'license. Copyright (c) {date.today().year} Triad National Security, LLC. ' \ + f'All rights reserved. Copyright (c) {date.today().year} Lawrence Livermore ' \ + f'National Security, LLC. All rights reserved. Copyright (c) ' \ + f'{date.today().year} UT-Battelle, LLC. All rights reserved.' +author = 'gemoetric_features 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 @@ -96,14 +102,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 @@ -183,3 +182,20 @@ build_quick_start() 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" -- 1.7.2 doesn't build +smv_tag_whitelist = r'^(?!1.7.2)\d+\.\d+.\d+$' +smv_branch_whitelist = 'main' +smv_remote_whitelist = 'origin' diff --git a/docs/index.rst b/docs/index.rst index d5132fbb..233e4084 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -30,9 +30,3 @@ Indices and tables ================== * :ref:`genindex` - -.. toctree:: - :caption: Versions - :maxdepth: 1 - - versions diff --git a/docs/versions.rst b/docs/versions.rst deleted file mode 100644 index 61ffa2a1..00000000 --- a/docs/versions.rst +++ /dev/null @@ -1,74 +0,0 @@ -Versions -======== - -================ =============== -Documentation On GitHub -================ =============== -`stable`_ `main`_ -`v0.1.7`_ `0.1.7`_ -`v0.1.8`_ `0.1.8`_ -`v0.1.9`_ `0.1.9`_ -`v0.1.10`_ `0.1.10`_ -`v0.1.11`_ `0.1.11`_ -`v0.1.12`_ `0.1.12`_ -`v0.1.13`_ `0.1.13`_ -`v0.2.0`_ `0.2.0`_ -`v0.3.0`_ `0.3.0`_ -`v0.4.0`_ `0.4.0`_ -`v0.5.0`_ `0.5.0`_ -`v0.6.0`_ `0.6.0`_ -`v0.7.0`_ `0.7.0`_ -`v0.8.0`_ `0.8.0`_ -`v1.0.0`_ `1.0.0`_ -`v1.0.1`_ `1.0.1`_ -`v1.1.0`_ `1.1.0`_ -`v1.2.0`_ `1.2.0`_ -`v1.3.0`_ `1.3.0`_ -`v1.4.0`_ `1.4.0`_ -`v1.5.0`_ `1.5.0`_ -================ =============== - -.. _`stable`: ../stable/index.html -.. _`main`: https://github.com/MPAS-Dev/geometric_features/tree/main -.. _`v0.1.7`: ../0.1.7/index.html -.. _`0.1.7`: https://github.com/MPAS-Dev/geometric_features/tree/0.1.7 -.. _`v0.1.8`: ../0.1.8/index.html -.. _`0.1.8`: https://github.com/MPAS-Dev/geometric_features/tree/0.1.8 -.. _`v0.1.9`: ../0.1.9/index.html -.. _`0.1.9`: https://github.com/MPAS-Dev/geometric_features/tree/0.1.9 -.. _`v0.1.10`: ../0.1.10/index.html -.. _`0.1.10`: https://github.com/MPAS-Dev/geometric_features/tree/0.1.10 -.. _`v0.1.11`: ../0.1.11/index.html -.. _`0.1.11`: https://github.com/MPAS-Dev/geometric_features/tree/0.1.11 -.. _`v0.1.12`: ../0.1.12/index.html -.. _`0.1.12`: https://github.com/MPAS-Dev/geometric_features/tree/0.1.12 -.. _`v0.1.13`: ../0.1.13/index.html -.. _`0.1.13`: https://github.com/MPAS-Dev/geometric_features/tree/0.1.13 -.. _`v0.2.0`: ../0.2.0/index.html -.. _`0.2.0`: https://github.com/MPAS-Dev/geometric_features/tree/0.2.0 -.. _`v0.3.0`: ../0.3.0/index.html -.. _`0.3.0`: https://github.com/MPAS-Dev/geometric_features/tree/0.3.0 -.. _`v0.4.0`: ../0.4.0/index.html -.. _`0.4.0`: https://github.com/MPAS-Dev/geometric_features/tree/0.4.0 -.. _`v0.5.0`: ../0.5.0/index.html -.. _`0.5.0`: https://github.com/MPAS-Dev/geometric_features/tree/0.5.0 -.. _`v0.6.0`: ../0.6.0/index.html -.. _`0.6.0`: https://github.com/MPAS-Dev/geometric_features/tree/0.6.0 -.. _`v0.7.0`: ../0.7.0/index.html -.. _`0.7.0`: https://github.com/MPAS-Dev/geometric_features/tree/0.7.0 -.. _`v0.8.0`: ../0.8.0/index.html -.. _`0.8.0`: https://github.com/MPAS-Dev/geometric_features/tree/0.8.0 -.. _`v1.0.0`: ../1.0.0/index.html -.. _`1.0.0`: https://github.com/MPAS-Dev/geometric_features/tree/1.0.0 -.. _`v1.0.1`: ../1.0.1/index.html -.. _`1.0.1`: https://github.com/MPAS-Dev/geometric_features/tree/1.0.1 -.. _`v1.1.0`: ../1.1.0/index.html -.. _`1.1.0`: https://github.com/MPAS-Dev/geometric_features/tree/1.1.0 -.. _`v1.2.0`: ../1.2.0/index.html -.. _`1.2.0`: https://github.com/MPAS-Dev/geometric_features/tree/1.2.0 -.. _`v1.3.0`: ../1.3.0/index.html -.. _`1.3.0`: https://github.com/MPAS-Dev/geometric_features/tree/1.3.0 -.. _`v1.4.0`: ../1.4.0/index.html -.. _`1.4.0`: https://github.com/MPAS-Dev/geometric_features/tree/1.4.0 -.. _`v1.5.0`: ../1.5.0/index.html -.. _`1.5.0`: https://github.com/MPAS-Dev/geometric_features/tree/1.5.0