From 50750c4ccc4a436cda1f3919d28b209d1cced3bd Mon Sep 17 00:00:00 2001 From: "David L. Qiu" Date: Fri, 2 Feb 2024 12:37:42 -0800 Subject: [PATCH 1/3] add contributing documentation --- docs/contributing.md | 51 +++++++++++++++++++++++++++++++++++++++++++ mkdocs.yml | 52 +++++++++++++++++++++++--------------------- 2 files changed, 78 insertions(+), 25 deletions(-) create mode 100644 docs/contributing.md diff --git a/docs/contributing.md b/docs/contributing.md new file mode 100644 index 0000000..3300d87 --- /dev/null +++ b/docs/contributing.md @@ -0,0 +1,51 @@ +# 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 + +To install this project in editable mode, along with optional dependencies +needed to run tests and build documentation: + +``` +pip install -e ".[test,docs]" +``` + +## Documentation + +To build documentation: + +``` +mkdocs build +``` + +## Integration tests + +The NPM test dependencies must first be installed: + +``` +cd tests/ +npm install +cd .. +``` + +To run the integration tests: + +``` +pytest +``` + +To run a specific test file: + +``` +pytest tests/ +``` + +Notably helpful `pytest` options include: + +- `-rP`: print all standard output, which is hidden for passing tests by default. +- `-k `: run a specific test function (not file) by its name. diff --git a/mkdocs.yml b/mkdocs.yml index 9c78892..efa55a9 100644 --- a/mkdocs.yml +++ b/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 From 2e7ab0a746d62944078e35b476a34b1ed4e77dc9 Mon Sep 17 00:00:00 2001 From: "David L. Qiu" Date: Fri, 2 Feb 2024 12:40:18 -0800 Subject: [PATCH 2/3] suppress warning about unrecognized path --- docs/usage/WebSocket_API.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/usage/WebSocket_API.md b/docs/usage/WebSocket_API.md index 00983e5..56fbc7d 100644 --- a/docs/usage/WebSocket_API.md +++ b/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: From 8050ae0000e4ea17147764d8c8864e227e490a7b Mon Sep 17 00:00:00 2001 From: David Brochart Date: Fri, 9 Feb 2024 10:06:33 +0100 Subject: [PATCH 3/3] Add more details --- docs/contributing.md | 25 ++++++++++++++++++------- 1 file changed, 18 insertions(+), 7 deletions(-) diff --git a/docs/contributing.md b/docs/contributing.md index 3300d87..460ad04 100644 --- a/docs/contributing.md +++ b/docs/contributing.md @@ -8,26 +8,37 @@ 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 documentation: +To build the documentation and start a server: +```bash +mkdocs serve ``` -mkdocs build -``` + +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 .. @@ -36,12 +47,12 @@ cd .. To run the integration tests: ``` -pytest +pytest -v ``` To run a specific test file: -``` +```bash pytest tests/ ```