enh: split out ci jobs and test them for a cleaner build (#139)

* enh: split out ci jobs

* enh: Fix linting CI jobs

* fix: test ci jobs

* fix: docs CI BUILDS

* Changelog

* fix: broken tests

Author: lwasser

CHANGELOG.md

@@ -2,6 +2,8 @@
 
 ## [Unreleased]
 
+* Fix docs CI builds to to simplify maintenance and feedback on jobs (@lwasser, #127, #138)
+
 ## [v0.6.7]
 
 ### Fixed
@@ -13,7 +15,7 @@
 * bug: ensure sphinx build works by @lwasser in https://github.com/pyOpenSci/pyos-package-template/pull/130
 * Move all dependencies to `optional.deps` and use hatch features (@lwasser, #131)
 
-### Added 
+### Added
 * Add and configure Dependabot (@agriyakhetarpal, #79)
 
 ### Contributors

template/pyproject.toml.jinja

@@ -70,6 +70,9 @@ Documentation = "{{ dev_platform_url }}/{{ username }}/{{ project_slug }}/blob/m
 Download = "https://pypi.org/project/{{ project_slug }}/#files"
 
 [project.optional-dependencies]
+# The groups below should be in the [development-groups] table
+# They are here now because hatch hasn't released support for them but plans to
+# in Mid November 2025.
 dev = [
     "hatch",
     "pre-commit",
@@ -101,7 +104,6 @@ docs = [
 
 build = [
     "pip-audit",
-    "pip",
     "twine",
 ]
 
@@ -113,7 +115,7 @@ tests = [
     "pytest-randomly",
     "pytest-xdist",
 ]
-{% endif %}
+{%- endif %}
 
 {%- if use_lint %}
 style = [
@@ -140,12 +142,12 @@ types = [
 [tool.hatch.build]
 only-packages = true
 
-# This tells Hatch to build the package from the src/me directory.
+# This tells Hatch to build the package from the src/ directory.
 # Read more about src layouts here: https://www.pyopensci.org/python-package-guide/package-structure-code/python-package-structure.html
 [tool.hatch.build.targets.wheel]
 packages = ["src/{{ package_name }}"]
 
-{%- if use_vcs_version %}
+{% if use_vcs_version %}
 [tool.hatch.build.hooks.vcs]
 version-file = "src/{{ package_name }}/_version.py"
 
@@ -182,7 +184,7 @@ exclude_lines = ["pragma: no cover"]
 precision = 2
 {%- endif %}
 
-{%- if use_lint %}
+{% if use_lint %}
 [tool.ruff]
 line-length = 88
 
@@ -238,7 +240,7 @@ check-yield-types = false
 {%- if use_vcs_version %}
 exclude = "_version.py"
 {%- endif %}
-{%- endif %}
+{%- endif -%}
 
 {% if use_types %}
 # TODO: Adjust mypy configuration.
@@ -261,7 +263,6 @@ exclude = "_version.py"
 {%- endif %}
 
 {%- if use_hatch_envs %}
-
 # Use UV to create Hatch environments
 [tool.hatch.envs.default]
 installer = "uv"
@@ -289,7 +290,7 @@ check = [
 
 #--------------- Run tests ---------------#
 
-{% if use_test %}
+{%- if use_test %}
 [tool.hatch.envs.test]
 description = """Run the test suite."""
 features = [
@@ -300,7 +301,7 @@ features = [
 python = ["3.10", "3.11", "3.12", "3.13"]
 
 [tool.hatch.envs.test.scripts]
-run = "pytest {args:--cov={{ package_name }} --cov-report=term-missing}"
+run = "pytest {args:--cov={{ package_name }} --cov-report=term-missing --cov-report=xml}"
 {%- endif %}
 
 #--------------- Build and preview your documentation ---------------#
@@ -327,7 +328,7 @@ serve = ["sphinx-apidoc -o docs/api src/{{ package_name}}", "sphinx-autobuild do
 {%- endif %}
 {%- endif %}
 
-{%- if use_lint %}
+{% if use_lint %}
 #--------------- Format & style your code ---------------#
 
 [tool.hatch.envs.style]

template/{% if documentation == 'sphinx' %}docs{% endif %}/index.md.jinja

@@ -1,8 +1,46 @@
-# {{ project_name }}
+# Welcome to {{ project_name }}'s Documentation '
 
 ## Overview
 
-{{ package_description }}
+:::{toctree}
+:maxdepth: 2
+:hidden:
+:caption: Contents:
+
+Home <self>
+Documentation <documentation/index>
+:::
+
+This is the landing page of your docs. you can update it as you'd like to.
+This documentation example uses myst markdown as the primary documentation syntax.
+
+
+:::{button-link} <https://www.pyopensci.org/python-package-guide/documentation/hosting-tools/myst-markdown-rst-doc-syntax.html>
+:color: primary
+:class: sd-rounded-pill float-left
+
+Learn more about myst in our pyOpenSci packaging guide.
+
+:::
+
+Myst is a version of markdown that has more formatting flexibility.
+This is what a sphinx directive looks like using myst markdown formatting:
+
+```markdown
+:::{toctree}
+:maxdepth: 2
+:caption: Contents:
+:::
+
+```
+
+If you see syntax like the syntax below, you are looking at rst.
+
+```rst
+.. toctree::
+   :maxdepth: 2
+   :caption: Contents:
+```
 
 [API Documentation](./api/modules.rst)
 

template/{% if use_git and dev_platform == 'GitHub' %}.github{% endif %}/workflows/docs.yml.jinja

@@ -0,0 +1,28 @@
+name: Build Docs
+
+on:
+  pull_request:
+  push:
+    branches:
+      - main
+
+jobs:
+  build-docs:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v4.5.2
+{%- raw %}
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@e797f83bcb11b83ae66e0230d6156d7c80228e7c # v5.1.0
+        with:
+            python-version: ${{ matrix.python-version }}
+{% endraw %}
+      - name: Install hatch
+        run: |
+            python -m pip install --upgrade pip
+            python -m pip install hatch
+
+      - name: Build documentation using Hatch
+        run: |
+            hatch run docs:build

….github{% endif %}/workflows/release.yml …b{% endif %}/workflows/release.yml.jinjatemplate/{% if use_git and dev_platform == 'GitHub' %}.github{% endif %}/workflows/release.yml renamed to template/{% if use_git and dev_platform == 'GitHub' %}.github{% endif %}/workflows/release.yml.jinja template/{% if use_git and dev_platform == 'GitHub' %}.github{% endif %}/workflows/release.yml renamed to template/{% if use_git and dev_platform == 'GitHub' %}.github{% endif %}/workflows/release.yml.jinja

@@ -1,16 +1,17 @@
 name: Publish to PyPI
 
 on:
+  pull_request:
+  push:
+    branches:
+      - main
   release:
     types: [published]
 
 jobs:
-  prerequisites:
-    uses: ./.github/workflows/test.yml
   # Setup build separate from publish for added security
   # See https://github.com/pypa/gh-action-pypi-publish/issues/217#issuecomment-1965727093
   build:
-    needs: [prerequisites]
     runs-on: ubuntu-latest
     # Environment is encouraged for increased security
     steps:
@@ -23,22 +24,26 @@ jobs:
           fetch-tags: true
 
       - name: Setup Python
-        uses: actions/setup-python@e797f83bcb11b83ae66e0230d6156d7c80228e7c # v5
+        uses: actions/setup-python@e797f83bcb11b83ae66e0230d6156d7c80228e7c # v6.0.0
         with:
           # You can modify what version of Python you want to use for your release
           python-version: "3.11"
 
-      # Security recommends we should pin deps. Should we pin the workflow version?
       - name: Install hatch
-        uses: pypa/hatch@257e27e51a6a5616ed08a39a408a21c35c9931bc
+        run: |
+            python -m pip install --upgrade pip
+            python -m pip install hatch
 
       - name: Build package using Hatch
         run: |
-          hatch build
-          echo ""
-          echo "Generated files:"
-          ls -lh dist/
-
+{%- if use_hatch_envs %}
+            hatch run build:check
+{% else %}
+            hatch build
+{% endif %}
+            echo ""
+            echo "Generated files:"
+            ls -lh dist/
       # Store an artifact of the build to use in the publish step below
       - name: Store the distribution packages
         uses: actions/upload-artifact@330a01c490aca151604b8cf639adc76d48f6c5d4 # v4
@@ -50,15 +55,15 @@ jobs:
     name: >-
       Publish Python 🐍 distribution 📦 to PyPI
     # Modify the repo name below to be your project's repo name.
-    if: github.repository_owner == "{{ username }}"
+    if: github.repository_owner == '{{ username }}'
     needs:
       - build
     runs-on: ubuntu-latest
     # Environment required here for trusted publisher
     environment:
       name: pypi
       # Modify the url to be the name of your package
-      url: https://pypi.org/p/${{ package_name }}
+      url: https://pypi.org/p/{{ package_name }}
     permissions:
       id-token: write  # this permission is mandatory for PyPI publishing
     steps:
@@ -69,6 +74,6 @@ jobs:
           path: dist/
           merge-multiple: true
       - name: Publish package to PyPI
-        # Only publish to real PyPI on release
+        # Only publish to real PyPI on release. This action uses sigstore for additional security.
         if: github.event_name == 'release' && github.event.action == 'published'
-        uses: pypa/gh-action-pypi-publish@release/v1
+        uses: pypa/gh-action-pypi-publish@ed0c53931b1dc9bd32cbe73a98c7f6766f8a527e #v1.13.0

template/{% if use_git and dev_platform == 'GitHub' %}.github{% endif %}/workflows/test.yml.jinja

@@ -1,44 +1,14 @@
-name: Test Suite
-
+name: Run Tests
+# Run the test suite on pull requests and pushes to main branch
 on:
-  workflow_dispatch: {}
-  workflow_call: {}
+  pull_request:
+  push:
+    branches:
+      - main
+  schedule:
+    - cron: '0 23 * * Sun'
 
 jobs:
-{%- if use_lint %}
-{%- raw %}
-  lint:
-    runs-on: ${{ matrix.os }}
-    strategy:
-      fail-fast: false
-      matrix:
-        os: [ubuntu-latest]
-        python-version: ["3.10"]
-
-    steps:
-      - uses: actions/checkout@v4
-
-      - name: Set up Python ${{ matrix.python-version }}
-        uses: actions/setup-python@v5
-        with:
-          python-version: ${{ matrix.python-version }}
-{%- endraw %}
-
-{%- if use_hatch_envs %}
-      - name: Install hatch
-        uses: pypa/hatch@install
-
-      - name: Check code style
-        run: hatch run style:code
-
-      - name: Check docstrings
-        run: hatch run style:docstrings
-
-      - name: Build documentation
-        run: hatch run docs:build
-{%- endif %}
-{%- endif %}
-
 {%- raw %}
   test:
     runs-on: ${{ matrix.os }}
@@ -49,37 +19,43 @@ jobs:
         python-version: ["3.10", "3.13"]
 
     steps:
-    - uses: actions/checkout@v4
+    - uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v4.5.2
 
     - name: Set up Python ${{ matrix.python-version }}
-      uses: actions/setup-python@v5
+      uses: actions/setup-python@e797f83bcb11b83ae66e0230d6156d7c80228e7c # v5.1.0
       with:
         python-version: ${{ matrix.python-version }}
 {%- endraw %}
 
 {%- if use_hatch_envs %}
     - name: Install hatch
-      uses: pypa/hatch@install
-
-    - name: Check installation
-      run: hatch run install:check
-
-    - name: Check dependencies
-      run: hatch run audit:check
-
-{%- if use_types %}
-    - name: Check types
-      run: hatch run types:check
-{%- endif %}
-
-{%- if use_test %}
+      run: |
+        python -m pip install --upgrade pip
+        python -m pip install hatch
 {%- raw %}
-    - name: Test suite
+    - name: Run test suite
       run: hatch run +py=${{ matrix.python-version }} test:run
-
-    - name: Report coverage
-      shell: bash
-      run: bash <(curl -s https://codecov.io/bash)
 {%- endraw %}
+
+{%- else %}
+    - name: Install test deps
+      run: |
+        python -m pip install --upgrade pip
+        python -m pip install -e ".[tests]"
+
+    - name: Run test suite
+      run: |
+        pytest --cov={{ package_name }} --cov-report=term-missing --cov-report=xml
 {%- endif %}
-{%- endif %}
+    # If you use this step and have a private repo- then you will need to get a
+    # token from codecov and
+    # save it as a github secret called CODECOV_TOKEN
+{%- raw %}
+    - name: Upload to codecov
+      if: runner.os == 'macOS' && matrix.python-version == '3.13'
+      uses: codecov/codecov-action@5a1091511ad55cbe89839c7260b706298ca349f7  # v5.5.1
+      with:
+        #token: ${{ secrets.CODECOV_TOKEN }}
+        verbose: true
+        files: ./coverage.xml
+{% endraw %}