Add contributing documentation (#12)

* add contributing documentation

* suppress warning about unrecognized path

* Add more details

---------

Co-authored-by: David Brochart <[email protected]>

docs/contributing.md

@@ -0,0 +1,62 @@
+# Contributing guide
+
+This chapter is reserved for developers who wish to contribute to
+`pycrdt-websocket`.
+
+All commands are to be run from the root of the repository unless otherwise
+specified.
+
+## Developer installation
+
+It is recommended to use a package manager such as [pixi](https://prefix.dev/docs/pixi/overview).
+You will need to install `pip` and `npm`:
+
+```bash
+pixi init
+pixi add pip nodejs
+pixi shell
+```
+
+To install this project in editable mode, along with optional dependencies
+needed to run tests and build documentation:
+
+```bash
+pip install -e ".[test,docs]"
+```
+
+## Documentation
+
+To build the documentation and start a server:
+
+```bash
+mkdocs serve
+```
+
+Then open a browser at [http://127.0.0.1:8000](http://127.0.0.1:8000).
+
+## Integration tests
+
+The NPM test dependencies must first be installed:
+
+```bash
+cd tests/
+npm install
+cd ..
+```
+
+To run the integration tests:
+
+```
+pytest -v
+```
+
+To run a specific test file:
+
+```bash
+pytest tests/<filename>
+```
+
+Notably helpful `pytest` options include:
+
+- `-rP`: print all standard output, which is hidden for passing tests by default.
+- `-k <test-name>`: run a specific test function (not file) by its name.

docs/usage/WebSocket_API.md

@@ -1,4 +1,5 @@
-The WebSocket object passed to `WebsocketProvider` and `WebsocketServer.serve` must implement the following API, defined as a [protocol class](../../reference/WebSocket):
+The WebSocket object passed to `WebsocketProvider` and `WebsocketServer.serve`
+must implement the following API, defined as a [protocol class](../reference/WebSocket.md):
 
 ```py
 class WebSocket:

mkdocs.yml

@@ -3,20 +3,20 @@ site_description: Async WebSocket connector for pycrdt
 repo_url: https://github.com/jupyter-server/pycrdt-websocket
 
 theme:
-  name: 'material'
+  name: "material"
   palette:
     - scheme: default
-      primary: 'black'
-      accent: 'black'
+      primary: "black"
+      accent: "black"
       toggle:
-          icon: material/lightbulb-outline
-          name: Switch to dark mode
+        icon: material/lightbulb-outline
+        name: Switch to dark mode
     - scheme: slate
-      primary: 'black'
-      accent: 'black'
+      primary: "black"
+      accent: "black"
       toggle:
-          icon: material/lightbulb
-          name: Switch to light mode
+        icon: material/lightbulb
+        name: Switch to light mode
   features:
     - navigation.instant
     - navigation.top
@@ -27,20 +27,22 @@ theme:
     - content.code.copy
 
 nav:
-- Overview: index.md
-- install.md
-- Usage:
-  - usage/client.md
-  - usage/server.md
-  - usage/WebSocket_API.md
-- Code Reference:
-  - reference/WebSocket_provider.md
-  - reference/WebSocket_server.md
-  - reference/ASGI_server.md
-  - reference/Django_Channels_consumer.md
-  - reference/WebSocket.md
-  - reference/Room.md
-  - reference/Store.md
+  - Overview: index.md
+  - install.md
+  - Usage:
+      - usage/client.md
+      - usage/server.md
+      - usage/WebSocket_API.md
+  - Contributing:
+      - contributing.md
+  - Code Reference:
+      - reference/WebSocket_provider.md
+      - reference/WebSocket_server.md
+      - reference/ASGI_server.md
+      - reference/Django_Channels_consumer.md
+      - reference/WebSocket.md
+      - reference/Room.md
+      - reference/Store.md
 
 markdown_extensions:
   - pymdownx.snippets
@@ -53,5 +55,5 @@ markdown_extensions:
           format: !!python/name:pymdownx.superfences.fence_code_format
 
 plugins:
-- mkdocstrings:
-    default_handler: python
+  - mkdocstrings:
+      default_handler: python