Add documentation (#71)

* Add user documentation

* Add contributors documentation

* Add some user documentation

* Automatic application of license header

* Documentation about adding a chat in an extension

* Add some documentation about integrating jupyterlab-collaborative-chat

* Some corrections in the documentation

* Minor typo fixes

---------

Co-authored-by: github-actions[bot] <github-actions[bot]@users.noreply.github.com>
Co-authored-by: Jeremy Tuloup <jeremy.tuloup@gmail.com>

.readthedocs.yaml

@@ -0,0 +1,21 @@
+# Read the Docs configuration file
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+
+version: 2
+
+build:
+ os: ubuntu-22.04
+ tools:
+ python: "3.11"
+ nodejs: "18"
+
+# Build documentation in the docs/ directory with Sphinx
+sphinx:
+ configuration: docs/source/conf.py
+
+python:
+ install:
+ - method: pip
+ path: .
+ extra_requirements:
+ - docs

docs/Makefile

@@ -0,0 +1,23 @@
+# Copyright (c) Jupyter Development Team.
+# Distributed under the terms of the Modified BSD License.
+
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS ?=
+SPHINXBUILD ?= sphinx-build
+SOURCEDIR = source
+BUILDDIR = build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+ @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+ @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

docs/make.bat

@@ -0,0 +1,38 @@
+rem Copyright (c) Jupyter Development Team.
+rem Distributed under the terms of the Modified BSD License.
+
+@ECHO OFF
+
+pushd %~dp0
+
+REM Command file for Sphinx documentation
+
+if "%SPHINXBUILD%" == "" (
+ set SPHINXBUILD=sphinx-build
+)
+set SOURCEDIR=source
+set BUILDDIR=build
+
+%SPHINXBUILD% >NUL 2>NUL
+if errorlevel 9009 (
+ echo.
+ echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
+ echo.installed, then set the SPHINXBUILD environment variable to point
+ echo.to the full path of the 'sphinx-build' executable. Alternatively you
+ echo.may add the Sphinx directory to PATH.
+ echo.
+ echo.If you don't have Sphinx installed, grab it from
+ echo.https://www.sphinx-doc.org/
+ exit /b 1
+)
+
+if "%1" == "" goto help
+
+%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+goto end
+
+:help
+%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+
+:end
+popd

docs/requirements.txt

@@ -0,0 +1,3 @@
+sphinx
+myst-parser
+pydata_sphinx_theme

docs/source/conf.py

@@ -0,0 +1,33 @@
+# Copyright (c) Jupyter Development Team.
+# Distributed under the terms of the Modified BSD License.
+
+# Configuration file for the Sphinx documentation builder.
+#
+# For the full list of built-in configuration values, see the documentation:
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
+
+# -- Project information -----------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
+
+project = 'jupyter-chat'
+copyright = '2024, Jupyter Development Team'
+author = 'Jupyter Development Team'
+
+# -- General configuration ---------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
+
+extensions = [
+ 'myst_parser',
+ 'sphinx_copybutton'
+]
+
+templates_path = ['_templates']
+exclude_patterns = []
+
+myst_enable_extensions = ["attrs_block", "attrs_inline"]
+
+# -- Options for HTML output -------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
+
+html_theme = 'pydata_sphinx_theme'
+html_static_path = ['_static']

docs/source/developers/contributing/index.md

@@ -0,0 +1,16 @@
+# Contributing
+
+We would be glad to review all incoming contributions.
+
+This project is included in *jupyterlab* organization, please read the
+[jupyter contributing guide](https://docs.jupyter.org/en/latest/contributing/content-contributor.html).
+
+```{toctree}
+---
+maxdepth: 2
+---
+
+./jupyter-chat
+./jupyterlab-collaborative-chat
+./jupyterlab-ws-chat
+```

docs/source/developers/contributing/jupyter-chat.md

@@ -0,0 +1,22 @@
+# @jupyter/chat
+
+The `@jupyter/chat` package is a frontend package (React) compatible with jupyterlab.
+It is not an extension, and cannot be used on its own. It is designed to be used in an
+extension.\
+In this repository, it is currently used in `jupyterlab-collaborative-chat` and
+`jupyterlab-ws-chat`.
+
+## Building the package
+
+From the root of the repository:
+
+```bash
+# In the following command, 'jlpm' can be replaced with 'yarn'
+jlpm build:core
+```
+
+From the package itself (`./packages/jupyter-chat`):
+
+```bash
+jlpm build
+```

docs/source/developers/contributing/jupyterlab-collaborative-chat.md

@@ -0,0 +1,77 @@
+# Collaborative chat
+
+The `jupyterlab-collaborative-chat` extension adds collaborative chats to jupyterlab.
+
+## Development installation
+
+Installing this extension in development mode requires an environment with *python* and
+*nodejs*.
+
+```bash
+# In the following commands, 'mamba' can be replaced with 'conda'
+mamba create -n jupyter-chat python nodejs
+mamba activate jupyter-chat
+```
+
+The following commands install the extension in development mode:
+
+```bash
+# Install the extension
+./scripts/install.sh collaborative
+
+# Symlink the assets
+jupyter labextension develop --overwrite packages/jupyterlab-collaborative-chat
+```
+
+To uninstall it, run:
+
+```bash
+pip uninstall jupyterlab-collaborative-chat
+```
+
+## Building the assets
+
+Changes in typescript sources of `@jupyter/chat` or `jupyterlab-collaborative-chat` must
+be built again to be available in the jupyterlab.
+
+```bash
+jlpm build:collaborative
+```
+
+## Testing locally the extension
+
+`jupyterlab-collaborative-chat` package has unit tests and integration tests.
+
+### Unit tests
+
+There are a few unit tests in *packages/jupyterlab-collaborative-chat/src/\_\_tests\_\_*.
+
+They make use of [jest](https://jestjs.io/).
+
+The following commands run them:
+
+```bash
+cd ./packages/jupyterlab-collaborative-chat
+jlpm test
+```
+
+### Integration tests
+
+The integration tests are located in *packages/jupyterlab-collaborative-chat/ui-tests*.
+
+They make use of [playwright](https://playwright.dev/).
+
+The following commands run them:
+
+```bash
+cd ./packages/jupyterlab-collaborative-chat/ui-tests
+
+# Install the tests dependencies
+jlpm install
+
+# Install the tests browser
+jlpm playwright install
+
+# Run the tests
+jlpm test
+```

docs/source/developers/contributing/jupyterlab-ws-chat.md

@@ -0,0 +1,39 @@
+# Websocket chat
+
+The `jupyterlab-ws-chat` extension adds a chat panel relying on websocket for messaging.
+
+## Development installation
+
+Installing this extension in development mode requires an environment with *python* and
+*nodejs*.
+
+```bash
+# In the following commands, 'mamba' can be replaced with 'conda'
+mamba create -n jupyter-chat python nodejs
+mamba activate jupyter-chat
+```
+
+The following commands install the extension in development mode:
+
+```bash
+# Install the extension
+./scripts/install.sh ws
+
+# Symlink the assets
+jupyter labextension develop --overwrite packages/jupyterlab-ws-chat
+```
+
+To uninstall it, run:
+
+```bash
+pip uninstall jupyterlab-ws-chat
+```
+
+## Building the assets
+
+Changes in typescript sources of `@jupyter/chat` or `jupyterlab-ws-chat` must
+be build again to be available in the jupyterlab.
+
+```bash
+jlpm build:ws
+```