Skip to content

Commit

Permalink
split up docs
Browse files Browse the repository at this point in the history
  • Loading branch information
@bollwyvl
bollwyvl committed Nov 1, 2019
1 parent 92d2833 commit 1ca2510
Show file tree
Hide file tree
Showing 8 changed files with 427 additions and 360 deletions.
29 changes: 29 additions & 0 deletions CHANGELOG.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,29 @@
# CHANGELOG

## `@krassowski/jupyter-lsp 0.6.1`

- features
- adds an indicator to the statusbar
- dependencies
- removes unused npm dependencies

## `@krassowski/jupyter-lsp 0.6.0`

- features
- allows "rename" action in file editor
- and many other improvements, see the [release notes](https://github.com/krassowski/jupyterlab-lsp/releases/tag/v0.6.0)
- bugfixes
- handles some non-standard diagnostic responses
- testing
- adds browser-based testing for file editor
- dependencies
- requires `jupyter-lsp`

## `jupyter-lsp 0.6.0`

- features
- starts language servers on demand
- accepts configuration via Jupyter config system (traitlets) and python
`entry_point`s
- autodetects language servers for bash, CSS, LESS, SASS, Dockerfile, YAML, JS,
TypeScript, JSX, TSX, JSON, YAML
272 changes: 151 additions & 121 deletions py_src/jupyter_lsp/CONTRIBUTING.md → CONTRIBUTING.md
View file
Original file line number Diff line number Diff line change
@@ -1,168 +1,100 @@
# Contribute to jupyter-lsp
# Contribute to jupyterlab-lsp and jupyter-lsp :heart:

`jupyter-lsp` is [open source](../../LICENSE) software, and all contributions
conforming to good sense, good taste, and the
`jupyter-lsp` and `jupyterlab-lsp` are [open source](./LICENSE) software, and
all contributions conforming to good sense, good taste, and the
[Jupyter Code of Conduct][code-of-conduct] are welcome, and will be reviewed
by the contributors, time-permitting.

## How to Help
You can contribute to the project through:

You can contribute to `jupyter-lsp` by:

- creating [specs](#Specs)
- creating language server [specs](#Specs)
- you can publish them yourself (it might be a single file)...
- or advocate for adding your spec to the [github repository][jupyterlab-lsp]
and its various distributions
- these are great first issues, as you might not need to know any python or
javascript
- improving [documentation](#Documentation)
- tackling Big Issues from the [future roadmap](#Future-Roadmap-Items)
- tackling Big Issues from the [future roadmap](./ROADMAP.md)
- improving [testing](#Testing)
- reviewing pull requests

## Roadmap

- release on `pip`
- release on `conda`
- [#49](https://github.com/krassowski/jupyterlab-lsp/issues/49)
cookiecutter for pip-installable specs
## Set up the environment

## Future Roadmap Items
Development requires:

- add hook system to allow serverextensions/kernels to modify, inspect and
react to LSP messages
- `nodejs` 8 or later
- `python` 3.5+
- `jupyterlab` 1.1

## Specs
It is recommended to use a virtual environment (e.g. `virtualenv` or `conda env`)
for development.

It is convenient to collect common patterns for connecting to installed language
servers as `pip`-installable packages that Just Work with `jupyter-lsp`.

If an advanced user installs, locates, and configures, their own language
server it will always win vs an auto-configured one.

### Writing a spec

> See the built-in [specs](./specs) for implementations and some
> [helpers](./specs/utils.py).
A spec is a python function that accepts a single argument, the
`LanguageServerManager`, and returns a dictionary of the form:

```python
{
"python-language-server": { # the name of the implementation
"argv": ["python", "-m", "pyls"], # a list of command line arguments
"languages": ["python"] # a list of languages it supports
}
}
```bash
conda env update -n jupyterlab-lsp # create a conda env
source activate jupyterlab-lsp # activate it
# or...
pip install -r requirements-dev.txt # in a virtualenv, probably
# ... and install nodejs, somehow
```

The spec should only be advertised if the command _could actually_ be run:

- its runtime (e.g. `julia`, `nodejs`, `python`, `r`, `ruby`) is installed
- the language server itself is installed (e.g. `python-language-server`)
Install `jupyter-lsp` from source in your virtual environment:

#### Common Concerns

- some language servers need to have their connection mode specified
- the `stdio` interface is the only one supported by `jupyter_lsp`
- PRs welcome to support other modes!
- because of its VSCode heritage, many language servers use `nodejs`
- `LanguageServerManager.nodejs` will provide the location of our best
guess at where a user's `nodejs` might be found
- some language servers are hard to start purely from the command line
- use a helper script to encapsulate some complexity.
- See the [r spec](./specs/r_languageserver.py) for an example

#### Example: making a pip-installable `cool-language-server` spec

Consider the following (absolutely minimal) directory structure:

```
- setup.py
- jupyter_lsp_my_cool_language_server.py
```bash
python -m pip install -e .
```

> You should consider adding a LICENSE, some documentation, etc.
Define your spec:
Enable the server extension:

```python
# jupyter_lsp_my_cool_language_server.py
from shutil import which


def cool(app):
cool_language_server = shutil.which("cool-language-server")

if not cool_language_server:
return {}

return {
"cool-language-server": {
"argv": [cool_language_server],
"languages": ["cool"]
}
}
```bash
jupyter serverextension enable --sys-prefix --py jupyter_lsp
```

Tell `pip` how to package your spec:
Install `npm` dependencies, build TypeScript packages, and link
to JupyterLab for development:

```python
# setup.py
import setuptools
setuptools.setup(
name="jupyter-lsp-my-cool-language-server",
py_modules=["jupyter_lsp_my_cool_language_server"],
entry_points={
"jupyter_lsp_spec_v0": [
"cool-language-server":
"jupyter_lsp_my_cool_language_server:cool"
]
}
)
```bash
jlpm
jlpm build
jlpm lab:link
```

Test it!
## Frontend Development

To rebuild the packages and the JupyterLab app:

```bash
python -m pip install -e .
jlpm build
jupyter lab build
```

Build it!
To watch the files and build continuously:

```bash
python setup.py sdist bdist_wheel
jlpm build --watch # leave this running...
jupyter lab --watch # ...in another terminal
```

## Contributing to `jupyter-lsp`

### Set up the environment
To check and fix code style:

```bash
conda env update -n jupyterlab-lsp # create a conda env
source activate jupyterlab-lsp # activate it
# or...
pip install -r requirements-dev.txt # in a virtualenv, probably
# ... and install nodejs, somehow
jlpm lint
```

Install a development version from `master` in your virtual environment:
To run test the suite:

```bash
python -m pip install -e .
jupyter labextension install .
jlpm test
```

## Testing `jupyter-lsp`
## Server Development

### Unit & Code Style Tests
### Testing `jupyter-lsp`

```bash
python scripts/utest.py
```

### Browser-based Acceptance Tests
## Browser-based Acceptance Tests

The browser tests will launch JupyterLab on a random port and exercise the
Language Server features with [Robot Framework][] and [SeleniumLibrary][].
Expand All @@ -171,19 +103,17 @@ Language Server features with [Robot Framework][] and [SeleniumLibrary][].
[seleniumlibrary]: https://github.com/robotframework/seleniumlibrary

First, ensure you've prepared JupyterLab for `jupyterlab-lsp`
[development](../../README.md#development).
[frontend](#frontend-development) and [server](#server-development) development.

Prepare the enviroment:

```bash
conda env update -n jupyterlab-lsp --file environment-atest.yml
# or
pip install -r requirements-atest.txt # ... and install geckodriver, somehow
apt-get install firefox-geckodriver # ... e.g. on debian/ubuntu
```

> Ubuntu users can install geckodriver with `apt install firefox-geckodriver`.
> Ensure you have run `jupyter labextension install .` in the root of the repository.
Run the tests:

```bash
Expand Down Expand Up @@ -239,8 +169,108 @@ black py_src
> - sphinx
> - one of the sphinx/ipynb connectors
[language-server]: https://microsoft.github.io/language-server-protocol/specification
[jupyter-server-proxy]: https://github.com/jupyterhub/jupyter-server-proxy
[lsp-implementations]: https://microsoft.github.io/language-server-protocol/implementors/servers
[jupyterlab-lsp]: https://github.com/krassowski/jupyterlab-lsp.git
[code-of-conduct]: https://github.com/jupyter/governance/blob/master/conduct/code_of_conduct.md

### Specs

It is convenient to collect common patterns for connecting to installed language
servers as `pip`-installable packages that Just Work with `jupyter-lsp`.

If an advanced user installs, locates, and configures, their own language
server it will always win vs an auto-configured one.

#### Writing a spec

> See the built-in [specs](./specs) for implementations and some
> [helpers](./specs/utils.py).
A spec is a python function that accepts a single argument, the
`LanguageServerManager`, and returns a dictionary of the form:

```python
{
"python-language-server": { # the name of the implementation
"argv": ["python", "-m", "pyls"], # a list of command line arguments
"languages": ["python"] # a list of languages it supports
}
}
```

The spec should only be advertised if the command _could actually_ be run:

- its runtime (e.g. `julia`, `nodejs`, `python`, `r`, `ruby`) is installed
- the language server itself is installed (e.g. `python-language-server`)

##### Common Concerns

- some language servers need to have their connection mode specified
- the `stdio` interface is the only one supported by `jupyter_lsp`
- PRs welcome to support other modes!
- because of its VSCode heritage, many language servers use `nodejs`
- `LanguageServerManager.nodejs` will provide the location of our best
guess at where a user's `nodejs` might be found
- some language servers are hard to start purely from the command line
- use a helper script to encapsulate some complexity.
- See the [r spec](./specs/r_languageserver.py) for an example

##### Example: making a pip-installable `cool-language-server` spec

Consider the following (absolutely minimal) directory structure:

```
- setup.py
- jupyter_lsp_my_cool_language_server.py
```

> You should consider adding a LICENSE, some documentation, etc.
Define your spec:

```python
# jupyter_lsp_my_cool_language_server.py
from shutil import which


def cool(app):
cool_language_server = shutil.which("cool-language-server")

if not cool_language_server:
return {}

return {
"cool-language-server": {
"argv": [cool_language_server],
"languages": ["cool"]
}
}
```

Tell `pip` how to package your spec:

```python
# setup.py
import setuptools
setuptools.setup(
name="jupyter-lsp-my-cool-language-server",
py_modules=["jupyter_lsp_my_cool_language_server"],
entry_points={
"jupyter_lsp_spec_v0": [
"cool-language-server":
"jupyter_lsp_my_cool_language_server:cool"
]
}
)
```

Test it!

```bash
python -m pip install -e .
```

Build it!

```bash
python setup.py sdist bdist_wheel
```
Loading

0 comments on commit 1ca2510

Please sign in to comment.