Documentation and type checking

.github/actions/install-with-conda/action.yml

@@ -0,0 +1,28 @@
+name: Install ETSpy with conda
+description: Uses conda package manager to install ETSpy and its dependencies
+inputs:
+  conda-env-name:
+    default: etspy
+    type: string
+  python-version:
+    default: "3.12"
+    type: string
+    required: true
+
+runs:
+  using: "composite"
+  steps:
+    - name: Setup conda environment
+      uses: conda-incubator/setup-miniconda@v3
+      with:
+        activate-environment: ${{ inputs.conda-env-name }}
+        environment-file: resources/etspy-dev.yml
+        auto-update-conda: true
+        python-version: ${{ inputs.python-version }}
+        auto-activate-base: false
+    - name: Conda list
+      run: conda list
+      shell: bash -el {0}
+    - name: Install etspy development
+      run: which pip && pip install -e ./
+      shell: bash -el {0}

.github/actions/install-with-poetry/action.yml

@@ -0,0 +1,34 @@
+name: Install ETSpy with poetry
+description: Uses poetry and CUDA action to install ETSpy and its dependencies
+inputs:
+  python-version:
+    default: "3.12"
+    type: string
+    required: true
+  with-cuda:
+    default: false
+    type: boolean
+  poetry-options:
+    default: ""
+    type: string
+    required: false
+
+runs:
+  using: "composite"
+  steps:
+    - name: Setup python interpreter
+      uses: actions/[email protected]
+      with:
+        python-version: ${{ inputs.python-version }}
+    - name: Setup poetry
+      uses: abatilo/[email protected]
+    - name: Install CUDA dependencies
+      if: ${{ inputs.with-cuda == 'true' }}
+      uses: Jimver/[email protected]
+      with:
+        method: network
+        sub-packages: '["cudart"]'
+        non-cuda-sub-packages: '["libcufft"]'
+    - name: Install ETSpy using poetry
+      run: poetry install ${{ inputs.poetry-options }}
+      shell: bash -el {0}

.github/actions/push-doc/action.yml

@@ -0,0 +1,73 @@
+# adapted from https://github.com/hyperspy/.github/blob/main/.github/workflows/push_doc.yml
+name: Push documentation
+description: Uses git to push the documentation to a particular branch
+inputs:
+  artifact_name:
+    description: 'The name of the github artifact containing the doc'
+    # if empty string, the current repository name is used
+    default: 'doc_html'
+    type: string
+  repository:
+    description: 'The repository, for example "usnistgov/etspy"'
+    # if empty string, the current repository name is used
+    default: ''
+    type: string
+  branch:
+    description: 'The branch to push to, for example "gh-pages"'
+    default: 'gh-pages'
+    type: string
+  output_path:
+    description: 'The path where the doc will be written'
+    default: '.'
+    type: string
+secrets:
+  access_token:
+    description: 'The access token required to push a repository: "GITHUB_TOKEN" if same repository of personal access token for separate repository'
+    # See https://github.com/ad-m/github-push-action/tree/master?tab=readme-ov-file#inputs
+
+runs:
+  using: "composite"
+  steps:
+    - uses: actions/checkout@v4
+      with:
+        fetch-depth: 0
+        repository: ${{ inputs.repository }}
+        ref: ${{ inputs.branch }} 
+        # Need to specify token here to enable pushing to other repository
+        token: ${{ env.ACCESS_TOKEN }}
+    - uses: actions/download-artifact@v4
+      with:
+        name: ${{ inputs.artifact_name }}
+        path: ${{ inputs.output_path }}
+    - name: list files
+      shell: bash -el {0}
+      run: |
+        ls
+    - name: Git status
+      shell: bash -el {0}
+      run: |
+        git status
+        git status -s
+        if [[ $(git status -s) ]]; then
+          HAS_CHANGES='true'
+        else
+          HAS_CHANGES='false'
+        fi
+        echo "HAS_CHANGES=${HAS_CHANGES}" >> $GITHUB_ENV
+    - name: Commit files
+      # Skip when there is nothing to commit
+      if: ${{ env.HAS_CHANGES == 'true' }}
+      shell: bash -el {0}
+      run: |
+        git config --local user.email "github-actions[bot]@users.noreply.github.com"
+        git config --local user.name "github-actions[bot]"
+        git add -A
+        git commit -m "Update docs build" -a
+
+    - name: Push changes
+      if: ${{ env.HAS_CHANGES == 'true' }}
+      uses: ad-m/[email protected]
+      with:
+        github_token: ${{ env.ACCESS_TOKEN }}
+        repository: ${{ inputs.repository }}
+        branch: ${{ inputs.branch }}

.github/workflows/docs.yml

@@ -0,0 +1,84 @@
+name: Documentation
+
+on: [push, pull_request]
+
+env:
+  DOC_SOURCE_PATH: docs
+  DOC_BUILD_PATH: docs/_build/html
+  DOC_ARTIFACT_NAME: doc_html
+  PAGES_BRANCH: nist-pages
+
+jobs:
+  build-documentation:
+    name: Build docs
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout latest commit
+        uses: actions/checkout@v4
+      - name: Set up CUDA and poetry
+        uses: ./.github/actions/install-with-poetry
+        with:
+          with-cuda: true
+          poetry-options: "--with=dev"
+          python-version: "3.11"   # use 3.11 due to flaky pystackreg install on 3.12
+      - name: Check links
+        run: |
+          cd ${{ env.DOC_SOURCE_PATH }}
+          poetry run make linkcheck
+      - name: Build docs
+        run: |
+          cd ${{ env.DOC_SOURCE_PATH }}
+          poetry run make html
+      - name: Upload built docs artifact
+        uses: actions/upload-artifact@v4
+        with:
+          path: ${{ env.DOC_BUILD_PATH }}
+          name: ${{ env.DOC_ARTIFACT_NAME }}
+
+  deploy-docs:
+    name: Deploy documentation 
+    runs-on: ubuntu-latest
+    needs: build-documentation
+    if: ${{ (github.repository_owner == 'usnistgov' && github.ref_name == 'master') || github.repository_owner != 'usnistgov' }}
+    permissions:
+      contents: write
+    steps:
+      - name: Checkout latest commit
+        uses: actions/checkout@v4
+      - name: Commit to ${{ env.PAGES_BRANCH }}
+        uses: ./.github/actions/push-doc
+        with:
+          artifact_name: ${{ env.DOC_ARTIFACT_NAME }}
+          branch: ${{ env.PAGES_BRANCH }}
+        env:
+          ACCESS_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+
+  # Push_dev:
+  #   needs: Build
+  #   # Push only on the "RELEASE_next_minor" and update the "dev" documentation
+  #   if: ${{ github.repository_owner == 'hyperspy' && github.ref_name == 'RELEASE_next_minor' }}
+  #   permissions:
+  #     # needs write permission to push the docs to gh-pages
+  #     contents: write
+  #   # Use the "reusable workflow" from the hyperspy organisation
+  #   uses: hyperspy/.github/.github/workflows/push_doc.yml@main
+  #   with:
+  #     repository: 'hyperspy/hyperspy-doc'
+  #     output_path: 'dev'
+  #   secrets:
+  #     access_token: ${{ secrets.PAT_DOCUMENTATION }}
+
+  # Push_tag:
+  #   needs: Build
+  #   # Push only on tag and update the "current" documentation
+  #   if: ${{ github.repository_owner == 'hyperspy' && startsWith(github.ref, 'refs/tags/') }}
+  #   permissions:
+  #     # needs write permission to push the docs to gh-pages
+  #     contents: write
+  #   # Use the "reusable workflow" from the hyperspy organisation
+  #   uses: hyperspy/.github/.github/workflows/push_doc.yml@main
+  #   with:
+  #     repository: 'hyperspy/hyperspy-doc'
+  #     output_path: 'current'
+  #   secrets:
+  #     access_token: ${{ secrets.PAT_DOCUMENTATION }}

.github/workflows/main.yml

@@ -1,24 +1,66 @@
 name: CI
-on: push
+on: [push, pull_request]
+
 jobs:
   format-checks:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
-      - run: pip install ruff isort
-      - run: isort . --check
-      - run: ruff check
+      - name: Set up poetry
+        uses: ./.github/actions/install-with-poetry
+        with:
+          with-cuda: false
+          poetry-options: "--only=dev"
+      - run: poetry run isort . --check
+      - run: poetry run ruff check
 
-  pytest:
-    runs-on: ubuntu-latest
-    container:
-      image: aaherzing/etspy:latest
+  conda-pytest:
+    name: "conda pytest: (${{ matrix.python-version }}, ${{ matrix.os }})"
+    runs-on: ${{ matrix.os }}
+    needs: [ format-checks ]
+    defaults:
+      run:
+        shell: bash -el {0}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: ["ubuntu-latest", "macos-latest", "windows-latest"]
+        python-version: ["3.10", "3.11", "3.12"]
+    steps:
+      - name: Checkout latest commit
+        uses: actions/checkout@v4
+      - name: Install with conda
+        uses: ./.github/actions/install-with-conda
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Run docstring example tests
+        run: pytest --doctest-modules --ignore=etspy/tests etspy/ 
+      - name: Run full test suite
+        id: full_conda_tests
+        if: always()
+        run: pytest etspy/tests/
+
+  poetry-pytest:
+    name: "poetry pytest: (${{ matrix.python-version }}, ${{ matrix.os }})"
+    runs-on: ${{ matrix.os }}
+    needs: [ format-checks ]
+    strategy:
+      fail-fast: false
+      matrix:
+        os: ["ubuntu-latest"]
+        python-version: ["3.10", "3.11", "3.12"]
     steps:
-    - uses: actions/checkout@v4
-    - name: Install ETSpy
-      run: pip install -e ./
-    - name: Run docstring example tests
-      run: pytest --doctest-modules --ignore=etspy/tests etspy/ 
-    - name: Run full test suite
-      if: always()
-      run: pytest etspy/tests/
+      - name: Checkout latest commit
+        uses: actions/checkout@v4
+      - name: Install with poetry
+        uses: ./.github/actions/install-with-poetry
+        with:
+          python-version: ${{ matrix.python-version }}
+          with-cuda: true
+          poetry-options: "--with=dev"
+      - name: Run docstring example tests
+        run: poetry run pytest --doctest-modules --ignore=etspy/tests etspy/ 
+      - name: Run full test suite
+        id: full_poetry_tests
+        if: always()
+        run: poetry run pytest etspy/tests/

.gitignore

@@ -50,6 +50,7 @@ coverage.xml
 *.cover
 .hypothesis/
 .pytest_cache/
+.ruff_cache/
 
 # Translations
 *.mo
@@ -68,6 +69,7 @@ instance/
 
 # Sphinx documentation
 docs/_build/
+docs/api/
 
 # PyBuilder
 target/