Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add documentation #71

Merged
merged 8 commits into from
Aug 14, 2024
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
21 changes: 21 additions & 0 deletions .readthedocs.yaml
Original file line number Diff line number Diff line change
@@ -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
23 changes: 23 additions & 0 deletions docs/Makefile
Original file line number Diff line number Diff line change
@@ -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)
38 changes: 38 additions & 0 deletions docs/make.bat
Original file line number Diff line number Diff line change
@@ -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
3 changes: 3 additions & 0 deletions docs/requirements.txt
Original file line number Diff line number Diff line change
@@ -0,0 +1,3 @@
sphinx
myst-parser
pydata_sphinx_theme
Binary file added docs/source/_static/images/code-toolbar-above.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added docs/source/_static/images/code-toolbar-below.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added docs/source/_static/images/code-toolbar-copy.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added docs/source/_static/images/code-toolbar-replace.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
33 changes: 33 additions & 0 deletions docs/source/conf.py
Original file line number Diff line number Diff line change
@@ -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']
16 changes: 16 additions & 0 deletions docs/source/developers/contributing/index.md
Original file line number Diff line number Diff line change
@@ -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
```
22 changes: 22 additions & 0 deletions docs/source/developers/contributing/jupyter-chat.md
Original file line number Diff line number Diff line change
@@ -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
```
Original file line number Diff line number Diff line change
@@ -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
```
39 changes: 39 additions & 0 deletions docs/source/developers/contributing/jupyterlab-ws-chat.md
Original file line number Diff line number Diff line change
@@ -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
```
Loading
Loading