addrress pr comments, add docs build info to CONTRIBUTING

Author: bollwyvl

.github/workflows/linkcheck.yaml

@@ -25,11 +25,9 @@ jobs:
       - uses: actions/setup-python@v4
         with:
           python-version: "3.11"
-          cache: pip
-          cache-dependency-path: pyproject.toml
 
       - name: Install deps
-        run: pip install .[docs]
+        run: pip install -r docs/requirements.txt
 
       - name: make linkcheck
         run: |

.github/workflows/publish.yaml

@@ -39,8 +39,6 @@ jobs:
       - uses: actions/setup-python@v4
         with:
           python-version: "3.11"
-          cache: pip
-          cache-dependency-path: pyproject.toml
 
       - uses: actions/setup-node@v3
         with:

.github/workflows/test.yaml

@@ -47,8 +47,6 @@ jobs:
       - uses: actions/setup-python@v4
         with:
           python-version: "${{ matrix.python-version }}"
-          cache: pip
-          cache-dependency-path: pyproject.toml
 
       - uses: actions/setup-node@v3
         with:
@@ -71,18 +69,15 @@ jobs:
         #
         #       Pytest options are set in tests/pytest.ini.
         run: |
-          set -eux
           pip install -vv $(ls ./dist/jupyter_server_proxy-*.whl)\[acceptance\] 'jupyterlab~=${{ matrix.jupyterlab-version }}.0'
 
       - name: List Python packages
         run: |
-          set -eux
           pip freeze
           pip check
 
       - name: Run tests
         run: |
-          set -eux
           JUPYTER_TOKEN=secret jupyter-${{ matrix.jupyter-app }} --config=./tests/resources/jupyter_server_config.py &
           sleep 5
           cd tests
@@ -100,21 +95,18 @@ jobs:
 
       - name: Check the Notebook Server extension is installed
         run: |
-          set -eux
           jupyter serverextension list
           jupyter serverextension list 2>&1 | grep -iE "jupyter_server_proxy.*OK" -
 
       - name: Check the Jupyter Server extension is installed
         run: |
-          set -eux
           pip install jupyter-server
           jupyter server extension list
           jupyter server extension list 2>&1 | grep -iE "jupyter_server_proxy.*OK" -
 
       - name: Install JupyterLab Extension
         if: matrix.jupyterlab-version == '2'
         run: |
-          set -eux
           export NODE_OPTIONS=--openssl-legacy-provider
           cd labextension
           jupyter labextension install . --no-build --debug
@@ -128,14 +120,12 @@ jobs:
         #
         if: ${{ !(matrix.jupyterlab-version == '2' && startsWith(matrix.python-version, '3.11')) }}
         run: |
-          set -eux
           jupyter labextension list
           jupyter labextension list 2>&1 | grep -iE '@jupyterhub/jupyter-server-proxy.*OK.*'
           python -m jupyterlab.browser_check
 
       - name: Run acceptance tests
         run: |
-          set -eux
           pytest -s -k "acceptance"
 
       - name: Upload acceptance test reports

CONTRIBUTING.md

@@ -19,7 +19,7 @@ jupyter server extension enable --sys-prefix jupyter_server_proxy
 
 Before running tests, you need a server that we can test against.
 
-```
+```bash
 JUPYTER_TOKEN=secret jupyter-lab --config=./tests/resources/jupyter_server_config.py --no-browser
 ```
 
@@ -81,3 +81,40 @@ and `jupyter_server_proxy/labextension` folders:
 cd labextension
 jlpm watch
 ```
+
+### Documentation
+
+The documentation uses a fairly standard [Sphinx](https://www.sphinx-doc.org)
+build chain, and requires `make` on Linux/MacOS, which cannot be installed with
+`pip`.
+
+In addition to any system packages, building the documentation requires
+additional packages. To install the needed packages:
+
+```bash
+pip install -r docs/requirements.txt
+```
+
+Once installed, enter the docs folder with:
+
+```bash
+cd docs
+```
+
+... then build the HTML site:
+
+```bash
+make
+```
+
+... or check that all hyperlinks can be resolved:
+
+```bash
+make linkcheck
+```
+
+... or start an auto-reloading server and open a web browser:
+
+```bash
+make devenv
+```

pyproject.toml

@@ -55,14 +55,6 @@ acceptance = [
     "notebook <7",
     "robotframework-jupyterlibrary >=0.4.2",
 ]
-docs = [
-    "myst-parser",
-    "sphinx-autobuild",
-    "sphinx-book-theme",
-    "sphinx-copybutton",
-    "sphinxext-opengraph",
-    "sphinxext-rediraffe",
-]
 
 [tool.hatch.version]
 source = "nodejs"