Merge branch 'build-distribution-packages'

.github/workflows/build.yml

@@ -69,8 +69,50 @@ jobs:
       - name: Upload the GitHub Pages artifact.
         uses: actions/upload-pages-artifact@v3
         with:
+          name: docs
           path: docs/_build/html/
-          retention-days: 60
+          retention-days: 90
+  test:
+    name: Run tests.
+    runs-on: ubuntu-latest
+    steps:
+      - name: Clone the repo.
+        uses: actions/checkout@v4
+      - name: Install Python.
+        uses: actions/setup-python@v5
+        with:
+          python-version-file: .default-python-version
+          cache: pip
+      - name: Run the tests.
+        run: |
+          python -Im pip install --quiet .[ci]
+          python -Im nox \
+            --non-interactive \
+            --session test
+  package:
+    name: Package the source.
+    runs-on: ubuntu-latest
+    steps:
+      - name: Clone the repo.
+        uses: actions/checkout@v4
+      - name: Install Python.
+        uses: actions/setup-python@v5
+        with:
+          python-version-file: .default-python-version
+          cache: pip
+      - name: Build the distribution package.
+        run: |
+          python -Im pip install --quiet .[ci]
+          python -Im nox \
+            --non-interactive \
+            --session package
+      - name: Upload the package artifact.
+        uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+          if-no-files-found: error
+          compression-level: 0  # packages are already compressed.
   matrix:
     name: Compute test matrix.
     runs-on: ubuntu-latest
@@ -91,7 +133,7 @@ jobs:
           PYTHON_VERSIONS=$( \
             python -Im \
               nox \
-                --session test \
+                --session testpackage \
                 --list \
                 --json \
               | jq \
@@ -106,9 +148,11 @@ jobs:
                 'split("\n")[:-1]' \
           )
           echo "python-versions=${PYTHON_VERSIONS}" | tee -a "${GITHUB_OUTPUT}"
-  test:
-    name: Test with Python ${{ matrix.python-version }}.
-    needs: matrix
+  testpackage:
+    name: Test package with Python ${{ matrix.python-version }}.
+    needs:
+      - package
+      - matrix
     strategy:
       fail-fast: false
       matrix:
@@ -122,23 +166,34 @@ jobs:
         with:
           python-version: ${{ matrix.python-version }}
           cache: pip
-      - name: Run the tests with Python ${{ matrix.python-version }}.
+      - name: Download the package artifact.
+        uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - name: Run tests on the package with Python ${{ matrix.python-version }}.
         env:
           PYTHON_VERSION: ${{ matrix.python-version }}
+        # NOTE: Since the package job builds the wheel from the sdist,
+        # test the wheel as it should cover both.
         run: |
           python -Im pip install --quiet .[ci]
           python -Im nox \
             --non-interactive \
-            --session "test-${PYTHON_VERSION}"
+            --session "testpackage-${PYTHON_VERSION}" \
+            -- \
+            dist/*.whl
   verify:
     name: Verify all checks passed.
     if: always()
     needs:
       - support
       - lint
       - docs
-      - matrix
       - test
+      - package
+      - matrix
+      - testpackage
     runs-on: ubuntu-latest
     steps:
       - name: Verify that all checks passed successfully.

.github/workflows/deploy.yml → .github/workflows/release.yml

@@ -2,8 +2,8 @@
 # Deploy the project.
 #
 # Requirements:
-# - Configure the repo to serve pages from a custom action.
-# - Make a protected github-pages environment for deploying the docs.
+# - Configure the repo to serve GitHub Pages from a custom action.
+# - Make a protected "release" environment for making releases.
 ##
 on:
   push:
@@ -14,7 +14,7 @@ env:
   PIP_DISABLE_PIP_VERSION_CHECK: true
 permissions: {}  # Explicitly set permissions on each job.
 concurrency:
-  group: pages
+  group: release
   cancel-in-progress: false
 jobs:
   build:
@@ -24,11 +24,13 @@ jobs:
     name: Deploy docs to GitHub Pages.
     needs: build
     environment:
-      name: github-pages
+      name: release
     permissions:
       pages: write
       id-token: write
     runs-on: ubuntu-latest
     steps:
       - name: Deploy the GitHub Pages site.
         uses: actions/deploy-pages@v4
+        with:
+          artifact_name: docs

MANIFEST.in

@@ -0,0 +1,13 @@
+# The file manifest for the distribution package.
+#
+# NOTE: This manifest is used for building the *distribution package*,
+# not local installations which include the experiments package.
+
+exclude **
+
+include LICENSE
+include README.rst
+include pyproject.toml
+include src/opda/**.py
+include tests/*.py
+include tests/opda/**.py

docs/tutorial/development.rst

@@ -55,24 +55,13 @@ are always run. To run all levels, use the ``--all-levels`` option:
 
    $ pytest --all-levels
 
-You can also use `nox <https://nox.thea.codes/en/stable/>`_ to run
-tests against all supported versions of Python and the core
-dependencies:
+You can also use `nox <https://nox.thea.codes/en/stable/>`_ to run the
+tests (e.g., in continuous integration):
 
 .. code-block:: console
 
    $ nox --session test
 
-There are many possible combinations of supported versions, so running
-these tests will take a long time. You might prefer to run a
-particular combination instead:
-
-.. code-block:: console
-
-   $ nox --session "test-3.11(numpy='1.26', scipy='1.12')"
-
-Use ``nox --list`` to see all supported combinations.
-
 
 Lint
 ====
@@ -186,3 +175,42 @@ In continuous integration, we build and test the documentation via
 .. code-block:: console
 
    $ nox --session docs
+
+
+Packaging
+=========
+Before building the package, you must preprocess
+:source-file:`pyproject.toml` to remove parts specific to local
+installations. The easiest way to do this is to run the ``package``
+session using `nox <https://nox.thea.codes/en/stable/>`_:
+
+.. code-block:: console
+
+   $ nox --session package
+
+After running this session, you'll find the ``dist/`` directory
+containing the built distributions. See the ``package`` session in
+:source-file:`noxfile.py` for further details.
+
+You can test the package against all supported versions of Python and
+the core dependencies using the ``testpackage`` nox session.
+
+.. code-block:: console
+
+   $ nox --session testpackage -- dist/*.whl
+
+It takes one positional argument: the package to test. The separator for
+options and arguments, ``--``, is required.
+
+As there are many possible combinations of supported versions, running
+all of these tests will take a long time. You might prefer to run a
+particular combination instead:
+
+.. code-block:: console
+
+   $ nox \
+       --session "testpackage-3.11(numpy='1.26', scipy='1.12')" \
+       -- \
+       dist/*.whl
+
+Use ``nox --list`` to see all supported combinations.

docs/tutorial/setup.rst

@@ -62,12 +62,12 @@ Install any of the following if you want to:
 
      $ pip install .[nbs]
 
-``opda[tests]``
+``opda[test]``
   Run the tests.
 
   .. code-block:: console
 
-     $ pip install .[tests]
+     $ pip install .[test]
 
 ``opda[lint]``
   Run the linter (when developing or extending opda):
@@ -83,6 +83,13 @@ Install any of the following if you want to:
 
      $ pip install .[docs]
 
+``opda[package]``
+  Build the distribution package.
+
+  .. code-block:: console
+
+     $ pip install .[package]
+
 ``opda[ci]``
   Run continuous integration commands using `nox
   <https://nox.thea.codes/en/stable/>`_:
@@ -95,7 +102,7 @@ You can also install any combination or all of the above:
 
 .. code-block:: console
 
-   $ pip install .[ci,docs,experiments,lint,nbs,tests]
+   $ pip install .[ci,docs,experiments,lint,nbs,package,test]
 
 See :doc:`Usage </tutorial/usage>` and :doc:`Development
 </tutorial/development>` for more information on how to use these