Skip to content

Commit 07d77b3

Browse files
bollwyvlbollwyvl
committed
format notebooks
1 parent 9e8f408 commit 07d77b3

13 files changed

+259
-659
lines changed

‎ci/job.docs.yml

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -31,10 +31,10 @@ jobs:
3131
- script: ${{ parameters.env_docs }} || ${{ parameters.env_docs }} || ${{ parameters.env_docs }}
3232
displayName: docs dependencies
3333

34-
- script: ${{ platform.activate }} jupyterlab-lsp && jlpm || jlpm || jlpm
34+
- script: ${{ platform.activate }} jupyterlab-lsp && jlpm || jlpm || jlpm
3535
displayName: install npm dependencies (for language servers)
3636

37-
- script: ${{ platform.activate }} python -m pip install -e . --no-deps --ignore-installed
37+
- script: ${{ platform.activate }} jupyterlab-lsp && sspython -m pip install -e . --no-deps --ignore-installed
3838
displayName: dev install python (for introspection)
3939

4040
- script: ${{ platform.activate }} jupyterlab-lsp && python scripts/docs.py

‎docs/Architecture.ipynb

Lines changed: 13 additions & 554 deletions
Large diffs are not rendered by default.

‎docs/CHANGELOG.ipynb

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -18,6 +18,7 @@
1818
"# this re-prints CHANGELOG.md, which is valuable to have in the root of the repo\n",
1919
"\n",
2020
"import pathlib\n",
21+
"\n",
2122
"import IPython\n",
2223
"\n",
2324
"contrib = pathlib.Path(\"../CHANGELOG.md\").read_text().split(\"\\n\", 1)[1]\n",

‎docs/Configuring.ipynb

Lines changed: 36 additions & 26 deletions
Original file line numberDiff line numberDiff line change
@@ -13,9 +13,10 @@
1313
"source": [
1414
"### Configuration Files\n",
1515
"\n",
16-
"Like the Jupyter Notebook server, JupyterHub, and other Jupyter interactive computing\n",
17-
"tools, `jupyter-lsp` can be configured via [Python or JSON files][notebook-config]\n",
18-
"in _well-known locations_. You can find out where to put them on your system with:\n",
16+
"Like the Jupyter Notebook server, JupyterHub, and other Jupyter interactive\n",
17+
"computing tools, `jupyter-lsp` can be configured via [Python or JSON\n",
18+
"files][notebook-config] in _well-known locations_. You can find out where to put\n",
19+
"them on your system with:\n",
1920
"\n",
2021
"[notebook-config]: https://jupyter-notebook.readthedocs.io/en/stable/config.html\n",
2122
"\n",
@@ -24,7 +25,7 @@
2425
"```\n",
2526
"\n",
2627
"They will be merged from bottom to top, and the directory where you launch your\n",
27-
"`notebook` server wins, making it easy to check in to version control. "
28+
"`notebook` server wins, making it easy to check in to version control."
2829
]
2930
},
3031
{
@@ -40,9 +41,10 @@
4041
"source": [
4142
"#### language_servers\n",
4243
"\n",
43-
"`jupyter-lsp` does not come with any Language Servers! However, we will try to use\n",
44-
"[known language servers](./Language%20Servers.ipynb) if they _are_ installed and we know about them: you can disable this behavior\n",
45-
"by configuring [autodetect](#autodetect). \n",
44+
"`jupyter-lsp` does not come with any Language Servers! However, we will try to\n",
45+
"use [known language servers](./Language%20Servers.ipynb) if they _are_ installed\n",
46+
"and we know about them: you can disable this behavior by configuring\n",
47+
"[autodetect](#autodetect).\n",
4648
"\n",
4749
"If you don't see an implementation for the language server you need, continue\n",
4850
"reading!\n",
@@ -57,9 +59,10 @@
5759
"source": [
5860
"The absolute minimum language server spec requires:\n",
5961
"\n",
60-
"- `argv`, a list of shell tokens to launch the server in `stdio` mode (as opposed to `tcp`),\n",
62+
"- `argv`, a list of shell tokens to launch the server in `stdio` mode (as\n",
63+
" opposed to `tcp`),\n",
6164
"- the `languages` which the server will respond to, and\n",
62-
"- the schema `version` of the spec (currently only `1`) \n",
65+
"- the schema `version` of the spec (currently only `1`)\n",
6366
"\n",
6467
"```python\n",
6568
"# ./jupyter_notebook_config.json ---------- unique! -----------\n",
@@ -84,12 +87,14 @@
8487
"cell_type": "markdown",
8588
"metadata": {},
8689
"source": [
87-
"A number of other options we hope to use to enrich the user experience are available in the\n",
88-
"[schema][].\n",
90+
"A number of other options we hope to use to enrich the user experience are\n",
91+
"available in the [schema][].\n",
8992
"\n",
90-
"[schema]: https://github.com/krassowski/jupyterlab-lsp/blob/master/py_src/jupyter_lsp/schema/schema.json\n",
93+
"[schema]:\n",
94+
" https://github.com/krassowski/jupyterlab-lsp/blob/master/py_src/jupyter_lsp/schema/schema.json\n",
9195
"\n",
92-
"More complex configurations that can't be hard-coded may benefit from the python approach:\n",
96+
"More complex configurations that can't be hard-coded may benefit from the python\n",
97+
"approach:\n",
9398
"\n",
9499
"```python\n",
95100
"# jupyter_notebook_config.py\n",
@@ -119,7 +124,8 @@
119124
"\n",
120125
"> default: `None`\n",
121126
"\n",
122-
"An absolute path to your `nodejs` executable. If `None`, `nodejs` will be detected in a number of well-known places."
127+
"An absolute path to your `nodejs` executable. If `None`, `nodejs` will be\n",
128+
"detected in a number of well-known places."
123129
]
124130
},
125131
{
@@ -130,9 +136,10 @@
130136
"\n",
131137
"> default: `True`\n",
132138
"\n",
133-
"`jupyter-lsp` will look for all [known language servers](#installing-language-servers).\n",
134-
"User-configured `language_servers` of the same implementation will be preferred\n",
135-
"over `autodetect`ed ones."
139+
"`jupyter-lsp` will look for all\n",
140+
"[known language servers](#installing-language-servers). User-configured\n",
141+
"`language_servers` of the same implementation will be preferred over\n",
142+
"`autodetect`ed ones."
136143
]
137144
},
138145
{
@@ -143,7 +150,8 @@
143150
"\n",
144151
"> default: `[]`\n",
145152
"\n",
146-
"Absolute paths to search for directories named `node_modules`, such as `nodejs`-backed language servers. The order is, roughly:\n",
153+
"Absolute paths to search for directories named `node_modules`, such as\n",
154+
"`nodejs`-backed language servers. The order is, roughly:\n",
147155
"\n",
148156
"- the folder where `notebook` or `lab` was launched\n",
149157
"- the JupyterLab `staging` folder\n",
@@ -159,8 +167,9 @@
159167
"\n",
160168
"> default: `[]`\n",
161169
"\n",
162-
"Additional places `jupyter-lsp` will look for `node_modules`. These will be checked\n",
163-
"_before_ `node_roots`, and should not contain the trailing `node_modules`."
170+
"Additional places `jupyter-lsp` will look for `node_modules`. These will be\n",
171+
"checked _before_ `node_roots`, and should not contain the trailing\n",
172+
"`node_modules`."
164173
]
165174
},
166175
{
@@ -169,12 +178,13 @@
169178
"source": [
170179
"### Python `entry_points`\n",
171180
"\n",
172-
"`pip`-installable packages in the same environment as the Jupyter `notebook` server\n",
173-
"can be automatically detected as providing [language_servers](#language_servers). These are a\n",
174-
"little more involved, but also more powerful: see more in [Contributing](Contributing.ipynb#Specs).\n",
175-
"Servers configured this way are loaded _before_ those defined in \n",
176-
"[configuration files](#Configuration-Files), so that a user can fine-tune their available\n",
177-
"servers."
181+
"`pip`-installable packages in the same environment as the Jupyter `notebook`\n",
182+
"server can be automatically detected as providing\n",
183+
"[language_servers](#language_servers). These are a little more involved, but\n",
184+
"also more powerful: see more in [Contributing](Contributing.ipynb#Specs).\n",
185+
"Servers configured this way are loaded _before_ those defined in\n",
186+
"[configuration files](#Configuration-Files), so that a user can fine-tune their\n",
187+
"available servers."
178188
]
179189
}
180190
],

‎docs/Contributing.ipynb

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -19,10 +19,11 @@
1919
"\n",
2020
"import pathlib\n",
2121
"import re\n",
22+
"\n",
2223
"import IPython\n",
2324
"\n",
2425
"contrib = pathlib.Path(\"../CONTRIBUTING.md\").read_text().split(\"\\n\", 1)[1]\n",
25-
"contrib = re.sub(r'^\\[(.*)\\]: \\./docs/(.*)$', '[\\\\1]: ./\\\\2', contrib, flags=re.M)\n",
26+
"contrib = re.sub(r\"^\\[(.*)\\]: \\./docs/(.*)$\", \"[\\\\1]: ./\\\\2\", contrib, flags=re.M)\n",
2627
"IPython.display.Markdown(contrib)"
2728
]
2829
}

‎docs/Extending.ipynb

Lines changed: 9 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -14,8 +14,9 @@
1414
"### jupyterlab-lsp\n",
1515
"\n",
1616
"> At present, `jupyterlab-lsp` is still in very early development, and does not\n",
17-
"> expose any runtime extension points. The [roadmap](./Roadmap.ipynb) lists several\n",
18-
"> potential points of extension, but will require some refactoring to achieve."
17+
"> expose any runtime extension points. The [roadmap](./Roadmap.ipynb) lists\n",
18+
"> several potential points of extension, but will require some refactoring to\n",
19+
"> achieve."
1920
]
2021
},
2122
{
@@ -41,15 +42,16 @@
4142
"Message listeners may choose to receive LSP messages immediately after being\n",
4243
"received from the client (e.g. `jupyterlab-lsp`) or a language server. All\n",
4344
"listeners of a message are scheduled concurrently, and the message is passed\n",
44-
"along **once all listeners return** (or fail). This allows listeners to, for example,\n",
45-
"modify files on disk before the language server reads them.\n",
45+
"along **once all listeners return** (or fail). This allows listeners to, for\n",
46+
"example, modify files on disk before the language server reads them.\n",
4647
"\n",
4748
"If a listener is going to perform an expensive activity that _shouldn't_ block\n",
4849
"delivery of a message, a non-blocking technique like\n",
4950
"[IOLoop.add_callback][add_callback] and/or a\n",
5051
"[queue](https://www.tornadoweb.org/en/stable/queues.html) should be used.\n",
5152
"\n",
52-
"[add_callback]: https://www.tornadoweb.org/en/stable/ioloop.html#tornado.ioloop.IOLoop.add_callback"
53+
"[add_callback]:\n",
54+
" https://www.tornadoweb.org/en/stable/ioloop.html#tornado.ioloop.IOLoop.add_callback"
5355
]
5456
},
5557
{
@@ -109,8 +111,8 @@
109111
"`lsp_message_listener` can be used as a decorator, accessed as part of a\n",
110112
"`serverextension`.\n",
111113
"\n",
112-
"This listener receives _all_ messages from the client and server, and prints them\n",
113-
"out.\n",
114+
"This listener receives _all_ messages from the client and server, and prints\n",
115+
"them out.\n",
114116
"\n",
115117
"```python\n",
116118
"from jupyter_lsp import lsp_message_listener\n",

‎docs/Installation.ipynb

Lines changed: 51 additions & 34 deletions
Original file line numberDiff line numberDiff line change
@@ -15,42 +15,46 @@
1515
"\n",
1616
"Delivering LSP features to your JupyterLab **requires** three pieces:\n",
1717
"\n",
18-
"- `jupyter_lsp` \n",
19-
" - runs in your `notebook` web application on your server\n",
20-
" - to run, you need: \n",
21-
" - `python >=3.5`\n",
22-
" - `notebook >=4.3`\n",
23-
"- `jupyterlab-lsp` \n",
24-
" - runs in your browser\n",
25-
" - to install it, you need:\n",
26-
" - `nodejs >8`\n",
27-
" - `jupyterlab >=1.1,<2`\n",
18+
"- `jupyter_lsp`\n",
19+
" - runs in your `notebook` web application on your server\n",
20+
" - to run, you need:\n",
21+
" - `python >=3.5`\n",
22+
" - `notebook >=4.3`\n",
23+
"- `jupyterlab-lsp`\n",
24+
" - runs in your browser\n",
25+
" - to install it, you need:\n",
26+
" - `nodejs >8`\n",
27+
" - `jupyterlab >=1.1,<2`\n",
2828
"- one or more language servers\n",
29-
" - run on your server\n",
30-
" - some can be automatically [detected](./Language%20Servers.ipynb) if installed\n",
31-
" - others also need to be [configured](./Configuring.ipynb#language_servers)"
29+
" - run on your server\n",
30+
" - some can be automatically [detected](./Language%20Servers.ipynb) if\n",
31+
" installed\n",
32+
" - others also need to be [configured](./Configuring.ipynb#language_servers)"
3233
]
3334
},
3435
{
3536
"cell_type": "markdown",
3637
"metadata": {},
3738
"source": [
3839
"### Fast Paths\n",
39-
"Here are two approches based on Jupyter documentation. If these do not meet your needs, try [The Harder Way](#The-Harder-Way)."
40+
"\n",
41+
"Here are two approches based on Jupyter documentation. If these do not meet your\n",
42+
"needs, try [The Harder Way](#The-Harder-Way)."
4043
]
4144
},
4245
{
4346
"cell_type": "markdown",
4447
"metadata": {},
4548
"source": [
4649
"#### conda (minimal python)\n",
50+
"\n",
4751
"```bash\n",
4852
"conda create -c conda-forge -n lsp 'python >=3.7,<3.8' 'jupyterlab=1.2' 'nodejs=11' python-language-server\n",
4953
"# Also consider: r-languageserver [*]\n",
5054
"source activate lsp\n",
5155
"pip install jupyter_lsp=0.7 --no-deps\n",
5256
"jupyter lab build\n",
53-
"jupyter lab \n",
57+
"jupyter lab\n",
5458
"```"
5559
]
5660
},
@@ -59,14 +63,17 @@
5963
"metadata": {},
6064
"source": [
6165
"#### docker (data science)\n",
62-
"This approach is based roughly on the [Jupyter docker-stacks documentation](https://github.com/jupyter/docker-stacks/tree/master/examples/docker-compose/notebook)."
66+
"\n",
67+
"This approach is based roughly on the\n",
68+
"[Jupyter docker-stacks documentation](https://github.com/jupyter/docker-stacks/tree/master/examples/docker-compose/notebook)."
6369
]
6470
},
6571
{
6672
"cell_type": "markdown",
6773
"metadata": {},
6874
"source": [
6975
"##### `Dockerfile`\n",
76+
"\n",
7077
"```dockerfile\n",
7178
"FROM jupyter/datascience-notebook:18ef2702c6a2\n",
7279
"\n",
@@ -93,19 +100,19 @@
93100
"##### `docker-compose.yml`\n",
94101
"\n",
95102
"```yaml\n",
96-
"version: \"2\"\n",
103+
"version: '2'\n",
97104
"\n",
98105
"services:\n",
99106
" notebook:\n",
100107
" build: .\n",
101108
" image: jupyterlab-lsp-notebook\n",
102109
" container_name: ${NAME}\n",
103110
" volumes:\n",
104-
" - \"work:/home/jovyan/work\"\n",
111+
" - 'work:/home/jovyan/work'\n",
105112
" ports:\n",
106-
" - \"${PORT}:8888\"\n",
113+
" - '${PORT}:8888'\n",
107114
" environment:\n",
108-
" USE_HTTPS: \"yes\"\n",
115+
" USE_HTTPS: 'yes'\n",
109116
" PASSWORD: ${PASSWORD}\n",
110117
"\n",
111118
"volumes:\n",
@@ -120,6 +127,7 @@
120127
"metadata": {},
121128
"source": [
122129
"##### Build and Start\n",
130+
"\n",
123131
"```bash\n",
124132
"PORT=8899 NAME=lsp PASSWORD=change-me-silly WORK_VOLUME=. docker-compose up\n",
125133
"```"
@@ -138,11 +146,13 @@
138146
"source": [
139147
"#### Get A Working JupyterLab environment\n",
140148
"\n",
141-
"Refer to the official [JupyterLab Installation Documentation](https://jupyterlab.readthedocs.io/en/stable/getting_started/installation.html) for your installation approach.\n",
149+
"Refer to the official\n",
150+
"[JupyterLab Installation Documentation](https://jupyterlab.readthedocs.io/en/stable/getting_started/installation.html)\n",
151+
"for your installation approach.\n",
142152
"\n",
143-
"| pip | conda | pipenv | poetry | `*` |\n",
144-
"|------------------|--------------------|----------|-----------|-----|\n",
145-
"| [lab][lab-pip] | [lab][lab-conda] | `*` | `*` | `*` |\n",
153+
"| pip | conda | pipenv | poetry | `*` |\n",
154+
"| -------------- | ---------------- | ------ | ------ | --- |\n",
155+
"| [lab][lab-pip] | [lab][lab-conda] | `*` | `*` | `*` |\n",
146156
"\n",
147157
"> `*` PRs welcome!\n",
148158
"\n",
@@ -153,8 +163,10 @@
153163
"jupyter lab\n",
154164
"```\n",
155165
"\n",
156-
"[lab-conda]: https://jupyterlab.readthedocs.io/en/stable/getting_started/installation.html#conda\n",
157-
"[lab-pip]: https://jupyterlab.readthedocs.io/en/stable/getting_started/installation.html#pip"
166+
"[lab-conda]:\n",
167+
" https://jupyterlab.readthedocs.io/en/stable/getting_started/installation.html#conda\n",
168+
"[lab-pip]:\n",
169+
" https://jupyterlab.readthedocs.io/en/stable/getting_started/installation.html#pip"
158170
]
159171
},
160172
{
@@ -163,13 +175,15 @@
163175
"source": [
164176
"#### Get a Working NodeJS\n",
165177
"\n",
166-
"The [JupyterLab Development Environment Documentation][nodejs-conda] shows some approaches for getting NodeJS.\n",
178+
"The [JupyterLab Development Environment Documentation][nodejs-conda] shows some\n",
179+
"approaches for getting NodeJS.\n",
167180
"\n",
168-
"| conda | `*` |\n",
169-
"|--------------------------|-----|\n",
170-
"| [nodejs][nodejs-conda] | `*` |\n",
181+
"| conda | `*` |\n",
182+
"| ---------------------- | --- |\n",
183+
"| [nodejs][nodejs-conda] | `*` |\n",
171184
"\n",
172-
"[nodejs-conda]: https://jupyterlab.readthedocs.io/en/stable/developer/extension_tutorial.html#set-up-a-development-environment\n",
185+
"[nodejs-conda]:\n",
186+
" https://jupyterlab.readthedocs.io/en/stable/developer/extension_tutorial.html#set-up-a-development-environment\n",
173187
"\n",
174188
"Verify your node works and is findable from python.\n",
175189
"\n",
@@ -196,10 +210,13 @@
196210
"source": [
197211
"### Next Step: Language Servers\n",
198212
"\n",
199-
"Now that you have `jupyterlab-lsp`, `jupyter_lsp` and all of their dependencies, you'll need some language servers. See:\n",
213+
"Now that you have `jupyterlab-lsp`, `jupyter_lsp` and all of their dependencies,\n",
214+
"you'll need some language servers. See:\n",
200215
"\n",
201-
"- [Language Servers](./Language%20Servers.ipynb) that will be found automatically once installed\n",
202-
"- [configuring](./Configuring.ipynb) `jupyter_lsp` for more control over which servers to load"
216+
"- [Language Servers](./Language%20Servers.ipynb) that will be found\n",
217+
" automatically once installed\n",
218+
"- [configuring](./Configuring.ipynb) `jupyter_lsp` for more control over which\n",
219+
" servers to load"
203220
]
204221
}
205222
],

0 commit comments

Comments
 (0)