Use hatch environments to simplify test, coverage, and docs build (#1007)

Author: blink1073

.github/workflows/python-tests.yml

@@ -31,20 +31,15 @@ jobs:
         uses: actions/checkout@v2
       - name: Base Setup
         uses: jupyterlab/maintainer-tools/.github/actions/base-setup@v1
-      - name: Install the Python dependencies
-        run: |
-          pip install -e ".[test,dev]" codecov
       - name: Run the tests
         if: ${{ !startsWith(matrix.python-version, 'pypy') && !startsWith(matrix.os, 'windows') }}
-        run: |
-          args="-vv --cov jupyter_server --cov-branch --cov-report term-missing:skip-covered"
-          python -m pytest $args  --cov-fail-under 70 || python -m pytest $args --lf
+        run: hatch run cov:test || hatch run cov:test --lf
       - name: Run the tests on pypy and windows
         if: ${{ startsWith(matrix.python-version, 'pypy') || startsWith(matrix.os, 'windows') }}
-        run: |
-          python -m pytest -vv || python -m pytest -vv --lf
+        run: hatch run test:test || hatch run test:test --lf
       - name: Coverage
         run: |
+          pip install codecov
           codecov
 
   pre-commit:
@@ -67,26 +62,28 @@ jobs:
           echo "or after-the-fact on already committed files with"
           echo "    pre-commit run --all-files --hook-stage=manual"
 
-  test_docs_and_examples:
-    name: Test Docs and Examples
+  test_docs:
+    name: Test Docs
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v2
+      - uses: jupyterlab/maintainer-tools/.github/actions/base-setup@v1
+      - run: hatch run docs:build
+
+  test_examples:
+    name: Test Examples
     timeout-minutes: 10
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v2
-      - name: Base Setup
-        uses: jupyterlab/maintainer-tools/.github/actions/base-setup@v1
+      - uses: jupyterlab/maintainer-tools/.github/actions/base-setup@v1
       - name: Install the Python dependencies for the examples
         run: |
           pip install -e ".[test]"
           cd examples/simple && pip install -e .
       - name: Run the tests for the examples
         run: |
           python -m pytest examples/simple
-      - name: Test the docs
-        run: |
-          cd docs
-          pip install -r doc-requirements.txt
-          make html SPHINXOPTS="-W"
 
   test_minimum_versions:
     name: Test Minimum Versions
@@ -101,8 +98,7 @@ jobs:
       - name: Install miniumum versions
         uses: jupyterlab/maintainer-tools/.github/actions/install-minimums@v1
       - name: Run the unit tests
-        run: |
-          pytest -vv -W default || pytest -vv -W default --lf
+        run: hatch run test:nowarn || hatch run test:nowarn --lf
 
   test_prereleases:
     name: Test Prereleases
@@ -126,7 +122,7 @@ jobs:
       - name: Run the tests
         run: |
           pip install jupyter_client@https://github.com/blink1073/jupyter_client/archive/refs/heads/synchronous_managers.zip
-          pytest -vv || pytest -vv --lf
+          pytest -vv -W default || pytest -vv -W default --lf
 
   make_sdist:
     name: Make SDist
@@ -146,7 +142,8 @@ jobs:
       - uses: jupyterlab/maintainer-tools/.github/actions/base-setup@v1
       - uses: jupyterlab/maintainer-tools/.github/actions/test-sdist@v1
         with:
-          test_command: pytest -vv || pytest -vv --lf
+          package_spec: .
+          test_command: hatch run test:test || hatch run test:test --lf
 
   check_links:
     name: Check Links

CONTRIBUTING.rst

@@ -24,10 +24,10 @@ The development version of the server requires `node <https://nodejs.org/en/down
 Once you have installed the dependencies mentioned above, use the following
 steps::
 
-    pip install --upgrade setuptools pip
+    pip install --upgrade pip
     git clone https://github.com/jupyter/jupyter_server
     cd jupyter_server
-    pip install -e ".[dev,test]"
+    pip install -e ".[test]"
 
 If you are using a system-wide Python installation and you only want to install the server for you,
 you can add ``--user`` to the install commands.
@@ -45,11 +45,10 @@ need to worry too much about your code style.
 As long as your code is valid,
 the pre-commit hook should take care of how it should look.
 `pre-commit` and its associated hooks will automatically be installed when
-you run ``pip install -e ".[dev,test]"``
+you run ``pip install -e ".[test]"``
 
-To install ``pre-commit`` manually, run the following::
+To install ``pre-commit`` hook manually, run the following::
 
-    pip install pre-commit
     pre-commit install
 
 
@@ -78,9 +77,9 @@ running other instances of Jupyter Server. You can try the following steps:
 
 1. Uninstall all instances of the jupyter_server package. These include any installations you made using
    pip or conda
-2. Run ``python3 -m pip install -e .`` in the jupyter_server repository to install the jupyter_server from there
+2. Run ``python -m pip install -e .`` in the jupyter_server repository to install the jupyter_server from there
 3. Run ``npm run build`` to make sure the Javascript and CSS are updated and compiled
-4. Launch with ``python3 -m jupyter_server --port 8989``, and check that the browser is pointing to ``localhost:8989``
+4. Launch with ``python -m jupyter_server --port 8989``, and check that the browser is pointing to ``localhost:8989``
    (rather than the default 8888). You don't necessarily have to launch with port 8989, as long as you use
    a port that is neither the default nor in use, then it should be fine.
 5. Verify the installation with the steps in the previous section.
@@ -98,36 +97,43 @@ To run the Python tests, use::
     pytest
     pytest examples/simple  # to test the examples
 
-Building the Docs
-=================
+You can also run the tests using ``hatch`` without installing test dependencies in your local environment::
+
+    pip install hatch
+    hatch run test:test
 
-To build the documentation you'll need `Sphinx <http://www.sphinx-doc.org/en/master/>`_,
-`pandoc <https://pandoc.org/>`_ and a few other packages.
+The command takes any argument that you can give to ``pytest``, e.g.::
 
-To install (and activate) a `conda environment`_ named ``jupyter_server_docs``
-containing all the necessary packages (except pandoc), use::
+    hatch run test:test -k name_of_method_to_test
 
-    conda env create -f docs/environment.yml
-    conda activate jupyter_server_docs
+You can also drop into a shell in the test environment by running::
 
-.. _conda environment:
-    https://conda.io/projects/conda/en/latest/user-guide/tasks/manage-environments.html#creating-an-environment-from-an-environment-yml-file
+    hatch -e test shell
+
+Building the Docs
+=================
 
-If you want to install the necessary packages with ``pip`` instead::
+Install the docs requirements using ``pip``::
 
-    pip install -r docs/doc-requirements.txt
+    pip install .[doc]
 
 Once you have installed the required packages, you can build the docs with::
 
     cd docs
     make html
 
-After that, the generated HTML files will be available at
-``build/html/index.html``. You may view the docs in your browser.
+You can also run the tests using ``hatch`` without installing test dependencies
+in your local environment.
+
+    pip install hatch
+    hatch run docs:build
 
-You can automatically check if all hyperlinks are still valid::
+You can also drop into a shell in the docs environment by running::
 
-    make linkcheck
+    hatch -e docs shell
+
+After that, the generated HTML files will be available at
+``build/html/index.html``. You may view the docs in your browser.
 
 Windows users can find ``make.bat`` in the ``docs`` folder.
 

docs/doc-requirements.txt

@@ -3,6 +3,3 @@ dependencies:
   - nodejs
   - python
   - pip
-  - pip:
-      - -r doc-requirements.txt
-      - ..

docs/environment.yml

@@ -62,24 +62,58 @@ test = [
     "pytest-tornasync",
     "pytest>=6.0",
     "requests",
+    "pre-commit"
 ]
-dev = [
-  "coverage",
-  "pre-commit",
-  "pytest-cov",
+docs = [
+    # needed because m2r uses deprecated APIs
+    # m2r is depended on by sphinxcontrib-openapi
+    "docutils<0.19",
+    "ipykernel",
+    "jinja2",
+    "jupyter_client",
+    "jupyter_server",
+    "mistune<1.0.0",
+    "myst-parser",
+    "nbformat",
+    "prometheus_client",
+    "pydata_sphinx_theme",
+    "Send2Trash",
+    "sphinxcontrib-openapi",
+    "sphinxcontrib_github_alt",
+    "sphinxemoji",
+    "tornado",
 ]
 
 [project.scripts]
 jupyter-server = "jupyter_server.serverapp:main"
 
+[tool.hatch.envs.docs]
+features = ["docs"]
+[tool.hatch.envs.docs.scripts]
+build = "make -C docs html SPHINXOPTS='-W'"
+
+[tool.hatch.envs.test]
+features = ["test"]
+[tool.hatch.envs.test.scripts]
+test = "python -m pytest -vv {args}"
+nowarn = "python -m pytest -vv -W default {args}"
+
+[tool.hatch.envs.cov]
+features = ["test"]
+dependencies = ["coverage", "pytest-cov"]
+[tool.hatch.envs.cov.env-vars]
+ARGS = "-vv --cov jupyter_server --cov-branch --cov-report term-missing:skip-covered"
+[tool.hatch.envs.cov.scripts]
+test = "python -m pytest $ARGS --cov-fail-under 70 {args}"
+
 [tool.hatch.version]
 path = "jupyter_server/_version.py"
 
 [tool.hatch.build]
 artifacts = ["jupyter_server/static/style"]
 
 [tool.hatch.build.hooks.jupyter-builder]
-dependencies = ["hatch-jupyter-builder>=0.3.3"]
+dependencies = ["hatch-jupyter-builder>=0.7.1"]
 build-function = "hatch_jupyter_builder.npm_builder"
 ensured-targets = [
   "jupyter_server/static/style/bootstrap.min.css",

pyproject.toml

@@ -3,3 +3,11 @@ sphinx:
   configuration: docs/source/conf.py
 conda:
   environment: docs/environment.yml
+python:
+  version: 3.8
+  install:
+    # install itself with pip install .
+    - method: pip
+      path: .
+      extra_requirements:
+        - docs