Merge branch 'main' into jp_web_app

Author: kevin-bates

docs/index.md

@@ -0,0 +1,37 @@
+# pytest-jupyter
+
+A set of [pytest plugins](https://docs.pytest.org/en/stable/plugins.html) for Jupyter libraries and extensions.
+
+## Basic Usage
+
+Install `pytest-jupyter` from PyPI using pip:
+```
+pip install pytest-jupyter
+```
+
+Once it's installed, all fixtures from `pytest-jupyter` will be discoverable by Pytest. Pass any fixture to your unit test function to begin using it, like so:
+
+```python
+async def test_jupyter_server_api(jp_fetch):
+    # Send request to a temporary Jupyter Server Web Application
+    response = await jp_fetch("api/spec.yml")
+
+    # Confirm that the request is successful.
+    assert response.code == 200
+```
+
+
+```{toctree}
+:maxdepth: 2
+:hidden:
+
+Core <plugins/jupyter_core>
+Server <plugins/jupyter_server>
+
+```
+
+## Search
+
+* {ref}`genindex`
+* {ref}`modindex`
+* {ref}`search`

docs/plugins/jupyter_core.md

@@ -0,0 +1,10 @@
+# Jupyter Core plugin
+
+The following fixtures are useful for setting up a test environment for Jupyter extensions and applications.
+
+## Fixtures
+
+```{eval-rst}
+.. automodule:: pytest_jupyter.jupyter_core
+    :members:
+```

docs/plugins/jupyter_server.md

@@ -0,0 +1,12 @@
+# Jupyter Server plugin
+
+The jupyter_server module provides fixtures for automatically setting-up/tearing-down Jupyter Servers.
+
+You can make requests to a *test server* using the `jp_fetch` and `jp_ws_fetch` fixtures.
+
+## Fixtures
+
+```{eval-rst}
+.. automodule:: pytest_jupyter.jupyter_server
+    :members:
+```

pytest_jupyter/jupyter_server.py

@@ -223,7 +223,19 @@ def jp_base_url():
 
 @pytest.fixture
 def jp_fetch(jp_serverapp, http_server_client, jp_auth_header, jp_base_url):
-    """Performs an HTTP request against the test server."""
+    """Sends an (asynchronous) HTTP request to a test server.
+
+    The fixture is a factory; it can be called like
+    a function inside a unit test. Here's a basic
+    example of how use this fixture:
+
+    .. code-block:: python
+
+        async def my_test(jp_fetch):
+
+            response = await jp_fetch("api", "spec.yaml")
+            ...
+    """
     def client_fetch(*parts, headers={}, params={}, **kwargs):
         # Handle URL strings
         path_url = url_escape(url_path_join(jp_base_url, *parts), plus=False)
@@ -240,7 +252,31 @@ def client_fetch(*parts, headers={}, params={}, **kwargs):
 
 @pytest.fixture
 def jp_ws_fetch(jp_serverapp, jp_auth_header, jp_http_port):
-    """Performs a websocket request against the test server."""
+    """Sends a websocket request to a test server.
+
+    The fixture is a factory; it can be called like
+    a function inside a unit test. Here's a basic
+    example of how use this fixture:
+
+    .. code-block:: python
+
+        async def my_test(jp_fetch, jp_ws_fetch):
+            # Start a kernel
+            r = await jp_fetch(
+                'api', 'kernels',
+                method='POST',
+                body=json.dumps({
+                    'name': "python3"
+                })
+            )
+            kid = json.loads(r.body.decode())['id']
+
+            # Open a websocket connection.
+            ws = await jp_ws_fetch(
+                'api', 'kernels', kid, 'channels'
+            )
+            ...
+    """
     def client_fetch(*parts, headers={}, params={}, **kwargs):
         # Handle URL strings
         path = url_escape(url_path_join(*parts), plus=False)