Skip to content

Commit 4a4b2ca

Browse files
fcollonvalkrassowski
fcollonval
and
krassowski
authored
Improve JavaScript API documentation (jupyterlab#14367)
* Add documentation interconnection Clean some API visibility * Upgrade typedoc to 0.24.1 * Fix doc warnings * Apply suggestions from code review Co-authored-by: Michał Krassowski <[email protected]> * Add typedoc-plugin-mdn-links * Add more external links * Fix RST URL syntax --------- Co-authored-by: Michał Krassowski <[email protected]>
1 parent 932360b commit 4a4b2ca

File tree

84 files changed

+357
-222
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

84 files changed

+357
-222
lines changed

‎docs/source/extension/extension_dev.rst

+2-3
Original file line numberDiff line numberDiff line change
@@ -55,7 +55,6 @@ Cookiecutters
5555
We provide several cookiecutters to create JupyterLab extensions:
5656

5757
- `extension-cookiecutter-ts <https://github.com/jupyterlab/extension-cookiecutter-ts>`_: Create a JupyterLab extension in TypeScript
58-
- `extension-cookiecutter-js <https://github.com/jupyterlab/extension-cookiecutter-js>`_: Create a JupyterLab extension in JavaScript
5958
- `mimerender-cookiecutter-ts <https://github.com/jupyterlab/mimerender-cookiecutter-ts>`_: Create a MIME Renderer JupyterLab extension in TypeScript
6059

6160
API Reference Documentation
@@ -64,7 +63,7 @@ API Reference Documentation
6463
Here is some autogenerated API documentation for JupyterLab and Lumino packages:
6564

6665
- `JupyterLab API Documentation <../api/>`_
67-
- `Lumino API Documentation <https://lumino.readthedocs.io/en/1.x/api/>`_
66+
- `Lumino API Documentation <https://lumino.readthedocs.io/en/latest/api/index.html>`_
6867

6968

7069
Overview of Extensions
@@ -204,7 +203,7 @@ The extension package containing the theme plugin must include all static assets
204203

205204
See the `JupyterLab Light Theme <https://github.com/jupyterlab/jupyterlab/tree/master/packages/theme-light-extension>`__ for an example.
206205

207-
See the `TypeScript theme cookiecutter <https://github.com/jupyterlab/theme-cookiecutter>`__ for a quick start to developing a theme plugin.
206+
See the `TypeScript extension cookiecutter <https://github.com/jupyterlab/extension-cookiecutter-ts>`__ (choosing ``theme`` as ``kind`` ) for a quick start to developing a theme plugin.
208207

209208
.. _source_extensions:
210209

‎docs/source/extension/extension_migration.rst

+24-16
Original file line numberDiff line numberDiff line change
@@ -117,7 +117,8 @@ bumped their major version (following semver convention). We want to point out p
117117
Removed ``modelDB`` from ``IAttachmentsModel.IOptions``.
118118
- ``@jupyterlab/buildutils`` from 3.x to 4.x
119119
* The ``create-theme`` script has been removed. If you want to create a new theme extension, you
120-
should use the `Theme Cookiecutter <https://github.com/jupyterlab/theme-cookiecutter>`_ instead.
120+
should use the `TypeScript extension Cookiecutter <https://github.com/jupyterlab/extension-cookiecutter-ts>`_
121+
(choosing ``theme`` as ``kind`` ) instead.
121122
* The ``add-sibling`` script has been removed. Check out :ref:`source_dev_workflow` instead.
122123
* The ``exitOnUuncaughtException`` util function has been renamed to ``exitOnUncaughtException`` (typo fix).
123124
- ``@jupyterlab/cells`` from 3.x to 4.x
@@ -273,9 +274,13 @@ bumped their major version (following semver convention). We want to point out p
273274
- ``@jupyterlab/filebrowser-extension`` from 3.x to 4.x
274275
Remove command ``filebrowser:create-main-launcher``. You can replace by ``launcher:create`` (same behavior)
275276
All launcher creation actions are moved to ``@jupyterlab/launcher-extension``.
277+
- ``@jupyterlab/imageviewer-extension`` from 3.x to 4.x
278+
Removed ``addCommands`` from public API
276279
- ``@jupyterlab/mainmenu`` from 3.x to 4.x
277280
* ``IMainMenu.addMenu`` signature changed from ``addMenu(menu: Menu, options?: IMainMenu.IAddOptions): void``
278281
to ``addMenu(menu: Menu, update?: boolean, options?: IMainMenu.IAddOptions): void``
282+
* Removed ``createEditMenu``, ``createFileMenu``, ``createKernelMenu``, ``createViewMenu``, ``createRunMenu``,
283+
``createTabsMenu``, ``createHelpMenu`` from public API.
279284
- ``@jupyterlab/notebook`` from 3.x to 4.x
280285
* ``NotebookWidgetFactory.IOptions`` has no ``sessionDialogs`` option any more.
281286
* The ``NotebookPanel._onSave`` method is now ``private``.
@@ -320,15 +325,18 @@ bumped their major version (following semver convention). We want to point out p
320325
This package is no longer present in JupyterLab. For documentation related to the shared models,
321326
please check out `@jupyter/ydoc documentation <https://jupyter-ydoc.readthedocs.io/en/latest>`_.
322327
- ``@jupyterlab/statusbar`` from 3.x to 4.x
323-
Setting ``@jupyterlab/statusbar-extension:plugin . startMode`` moved to ``@jupyterlab/application-extension:shell . startMode``
324-
Plugin ``@jupyterlab/statusbar-extension:mode-switch`` renamed to ``@jupyterlab/application-extension:mode-switch``
325-
Plugin ``@jupyterlab/statusbar-extension:kernel-status`` renamed to ``@jupyterlab/apputils-extension:kernel-status``
326-
Plugin ``@jupyterlab/statusbar-extension:running-sessions-status`` renamed to ``@jupyterlab/apputils-extension:running-sessions-status``
327-
Plugin ``@jupyterlab/statusbar-extension:line-col-status`` renamed to ``@jupyterlab/codemirror-extension:line-col-status``
328-
``HoverBox`` component moved from ``@jupyterlab/apputils`` to ``@jupyterlab/ui-components``.
328+
* Setting ``@jupyterlab/statusbar-extension:plugin . startMode`` moved to ``@jupyterlab/application-extension:shell . startMode``
329+
* Plugin ``@jupyterlab/statusbar-extension:mode-switch`` renamed to ``@jupyterlab/application-extension:mode-switch``
330+
* Plugin ``@jupyterlab/statusbar-extension:kernel-status`` renamed to ``@jupyterlab/apputils-extension:kernel-status``
331+
* Plugin ``@jupyterlab/statusbar-extension:running-sessions-status`` renamed to ``@jupyterlab/apputils-extension:running-sessions-status``
332+
* Plugin ``@jupyterlab/statusbar-extension:line-col-status`` renamed to ``@jupyterlab/codemirror-extension:line-col-status``
333+
* ``HoverBox`` component moved from ``@jupyterlab/apputils`` to ``@jupyterlab/ui-components``.
334+
* Removed ``STATUSBAR_PLUGIN_ID`` from public API.
329335
- ``@jupyterlab/terminal`` from 3.x to 4.x
330-
Xterm.js upgraded from 4.x to 5.x
331-
``IThemeObject.selection`` renamed to ``selectionBackground``
336+
* Xterm.js upgraded from 4.x to 5.x
337+
* ``IThemeObject.selection`` renamed to ``selectionBackground``
338+
- ``@jupyterlab/terminal-extension`` from 3.x to 4.x
339+
Removed ``addCommands`` from public API
332340
- ``@jupyterlab/toc`` from 3.x to 4.x
333341
``@jupyterlab/toc:plugin`` renamed ``@jupyterlab/toc-extension:registry``
334342
This may impact application configuration (for instance if the plugin was disabled).
@@ -355,17 +363,17 @@ bumped their major version (following semver convention). We want to point out p
355363
The renderer id must follow the convention ``<ISettingRegistry.IPlugin.id>.<propertyName>``. This is to
356364
ensure a custom renderer is not used for property with the same name but different schema.
357365
- ``@jupyterlab/translation`` from 3.x to 4.x
358-
Renamed the method ``locale`` into the property ``languageCode`` in the ``NullTranslator``
366+
Renamed the method ``locale`` into the property ``languageCode`` in the ``NullTranslator``
359367
- ``@jupyterlab/vdom`` and ``@jupyterlab/vdom-extension`` have been removed.
360-
The underlying [vdom](https://github.com/nteract/vdom) Python package is unmaintained.
361-
So it was decided to drop it from core packages.
368+
The underlying `vdom <https://github.com/nteract/vdom>`_ Python package is unmaintained.
369+
So it was decided to drop it from core packages.
362370
- ``jupyter.extensions.hub-extension`` from 3.x to 4.x
363371
* Renamed ``jupyter.extensions.hub-extension`` to ``@jupyterlab/hub-extension:plugin``.
364372
* Renamed ``jupyter.extensions.hub-extension:plugin`` to ``@jupyterlab/hub-extension:menu``.
365-
- TypeScript 4.7 update
366-
As a result of the update to TypeScript 4.7, a couple of interfaces have had their definitions changed.
367-
The ``anchor`` parameter of ``HoverBox.IOptions`` is now a ``DOMRect`` instead of ``ClientRect``.
368-
The ``CodeEditor.ICoordinate`` interface now extends ``DOMRectReadOnly`` instead of ``JSONObject, ClientRect``.
373+
- TypeScript 5.0 update
374+
As a result of the update to TypeScript 5.0, a couple of interfaces have had their definitions changed.
375+
The ``anchor`` parameter of ``HoverBox.IOptions`` is now a ``DOMRect`` instead of ``ClientRect``.
376+
The ``CodeEditor.ICoordinate`` interface now extends ``DOMRectReadOnly`` instead of ``JSONObject, ClientRect``.
369377
- React 18.2.0 update
370378
The update to React 18.2.0 (from 17.0.1) should be propagated to extensions as well.
371379
Here is the documentation about the `migration to react 18 <https://reactjs.org/blog/2022/03/08/react-18-upgrade-guide.html>`_.

‎package.json

+2-1
Original file line numberDiff line numberDiff line change
@@ -127,6 +127,7 @@
127127
},
128128
"devDependencies": {
129129
"lerna": "^6.4.1",
130-
"typedoc": "~0.23.25"
130+
"typedoc": "~0.24.1",
131+
"typedoc-plugin-mdn-links": "^3.0.3"
131132
}
132133
}

‎packages/application-extension/package.json

+1-1
Original file line numberDiff line numberDiff line change
@@ -56,7 +56,7 @@
5656
},
5757
"devDependencies": {
5858
"rimraf": "~3.0.0",
59-
"typedoc": "~0.23.25",
59+
"typedoc": "~0.24.1",
6060
"typescript": "~5.0.4"
6161
},
6262
"publishConfig": {

‎packages/application/package.json

+1-1
Original file line numberDiff line numberDiff line change
@@ -68,7 +68,7 @@
6868
"@types/jest": "^29.2.0",
6969
"jest": "^29.2.0",
7070
"rimraf": "~3.0.0",
71-
"typedoc": "~0.23.25",
71+
"typedoc": "~0.24.1",
7272
"typescript": "~5.0.4"
7373
},
7474
"publishConfig": {

‎packages/apputils-extension/package.json

+1-1
Original file line numberDiff line numberDiff line change
@@ -64,7 +64,7 @@
6464
},
6565
"devDependencies": {
6666
"rimraf": "~3.0.0",
67-
"typedoc": "~0.23.25",
67+
"typedoc": "~0.24.1",
6868
"typescript": "~5.0.4"
6969
},
7070
"publishConfig": {

‎packages/apputils/package.json

+1-1
Original file line numberDiff line numberDiff line change
@@ -73,7 +73,7 @@
7373
"@types/sanitize-html": "^2.3.1",
7474
"jest": "^29.2.0",
7575
"rimraf": "~3.0.0",
76-
"typedoc": "~0.23.25",
76+
"typedoc": "~0.24.1",
7777
"typescript": "~5.0.4"
7878
},
7979
"publishConfig": {

‎packages/attachments/package.json

+1-1
Original file line numberDiff line numberDiff line change
@@ -46,7 +46,7 @@
4646
},
4747
"devDependencies": {
4848
"rimraf": "~3.0.0",
49-
"typedoc": "~0.23.25",
49+
"typedoc": "~0.24.1",
5050
"typescript": "~5.0.4"
5151
},
5252
"publishConfig": {

‎packages/cells/package.json

+1-1
Original file line numberDiff line numberDiff line change
@@ -78,7 +78,7 @@
7878
"@types/react": "^18.0.26",
7979
"jest": "^29.2.0",
8080
"rimraf": "~3.0.0",
81-
"typedoc": "~0.23.25",
81+
"typedoc": "~0.24.1",
8282
"typescript": "~5.0.4"
8383
},
8484
"publishConfig": {

‎packages/codeeditor/package.json

+1-1
Original file line numberDiff line numberDiff line change
@@ -63,7 +63,7 @@
6363
"@types/jest": "^29.2.0",
6464
"jest": "^29.2.0",
6565
"rimraf": "~3.0.0",
66-
"typedoc": "~0.23.25",
66+
"typedoc": "~0.24.1",
6767
"typescript": "~5.0.4"
6868
},
6969
"publishConfig": {

‎packages/codemirror-extension/package.json

+1-1
Original file line numberDiff line numberDiff line change
@@ -55,7 +55,7 @@
5555
"devDependencies": {
5656
"@types/react": "^18.0.26",
5757
"rimraf": "~3.0.0",
58-
"typedoc": "~0.23.25",
58+
"typedoc": "~0.24.1",
5959
"typescript": "~5.0.4"
6060
},
6161
"publishConfig": {

‎packages/codemirror/package.json

+1-1
Original file line numberDiff line numberDiff line change
@@ -79,7 +79,7 @@
7979
"@types/jest": "^29.2.0",
8080
"jest": "^29.2.0",
8181
"rimraf": "~3.0.0",
82-
"typedoc": "~0.23.25",
82+
"typedoc": "~0.24.1",
8383
"typescript": "~5.0.4"
8484
},
8585
"publishConfig": {

‎packages/completer-extension/package.json

+1-1
Original file line numberDiff line numberDiff line change
@@ -48,7 +48,7 @@
4848
},
4949
"devDependencies": {
5050
"rimraf": "~3.0.0",
51-
"typedoc": "~0.23.25",
51+
"typedoc": "~0.24.1",
5252
"typescript": "~5.0.4"
5353
},
5454
"publishConfig": {

‎packages/completer/package.json

+1-1
Original file line numberDiff line numberDiff line change
@@ -66,7 +66,7 @@
6666
"@types/jest": "^29.2.0",
6767
"jest": "^29.2.0",
6868
"rimraf": "~3.0.0",
69-
"typedoc": "~0.23.25",
69+
"typedoc": "~0.24.1",
7070
"typescript": "~5.0.4"
7171
},
7272
"publishConfig": {

‎packages/console-extension/package.json

+1-1
Original file line numberDiff line numberDiff line change
@@ -58,7 +58,7 @@
5858
},
5959
"devDependencies": {
6060
"rimraf": "~3.0.0",
61-
"typedoc": "~0.23.25",
61+
"typedoc": "~0.24.1",
6262
"typescript": "~5.0.4"
6363
},
6464
"publishConfig": {

‎packages/console/package.json

+1-1
Original file line numberDiff line numberDiff line change
@@ -69,7 +69,7 @@
6969
"@types/jest": "^29.2.0",
7070
"jest": "^29.2.0",
7171
"rimraf": "~3.0.0",
72-
"typedoc": "~0.23.25",
72+
"typedoc": "~0.24.1",
7373
"typescript": "~5.0.4"
7474
},
7575
"publishConfig": {

‎packages/coreutils/package.json

+1-1
Original file line numberDiff line numberDiff line change
@@ -58,7 +58,7 @@
5858
"jest-junit": "^15.0.0",
5959
"rimraf": "~3.0.0",
6060
"ts-jest": "^29.1.0",
61-
"typedoc": "~0.23.25",
61+
"typedoc": "~0.24.1",
6262
"typescript": "~5.0.4"
6363
},
6464
"publishConfig": {

‎packages/coreutils/src/path.ts

+4-4
Original file line numberDiff line numberDiff line change
@@ -82,18 +82,18 @@ export namespace PathExt {
8282
* @param parts - The paths to join.
8383
*
8484
* #### Notes
85-
* The right-most parameter is considered {to}. Other parameters are considered an array of {from}.
85+
* The right-most parameter is considered \{to\}. Other parameters are considered an array of \{from\}.
8686
*
87-
* Starting from leftmost {from} parameter, resolves {to} to an absolute path.
87+
* Starting from leftmost \{from\} parameter, resolves \{to\} to an absolute path.
8888
*
89-
* If {to} isn't already absolute, {from} arguments are prepended in right to left order, until an absolute path is found. If after using all {from} paths still no absolute path is found, the current working directory is used as well. The resulting path is normalized, and trailing slashes are removed unless the path gets resolved to the root directory.
89+
* If \{to\} isn't already absolute, \{from\} arguments are prepended in right to left order, until an absolute path is found. If after using all \{from\} paths still no absolute path is found, the current working directory is used as well. The resulting path is normalized, and trailing slashes are removed unless the path gets resolved to the root directory.
9090
*/
9191
export function resolve(...parts: string[]): string {
9292
return removeSlash(posix.resolve(...parts));
9393
}
9494

9595
/**
96-
* Solve the relative path from {from} to {to}.
96+
* Solve the relative path from \{from\} to \{to\}.
9797
*
9898
* @param from - The source path.
9999
*

‎packages/csvviewer-extension/package.json

+1-1
Original file line numberDiff line numberDiff line change
@@ -52,7 +52,7 @@
5252
},
5353
"devDependencies": {
5454
"rimraf": "~3.0.0",
55-
"typedoc": "~0.23.25",
55+
"typedoc": "~0.24.1",
5656
"typescript": "~5.0.4"
5757
},
5858
"publishConfig": {

‎packages/csvviewer/package.json

+1-1
Original file line numberDiff line numberDiff line change
@@ -60,7 +60,7 @@
6060
"csv-spectrum": "^1.0.0",
6161
"jest": "^29.2.0",
6262
"rimraf": "~3.0.0",
63-
"typedoc": "~0.23.25",
63+
"typedoc": "~0.24.1",
6464
"typescript": "~5.0.4"
6565
},
6666
"publishConfig": {

‎packages/debugger-extension/package.json

+1-1
Original file line numberDiff line numberDiff line change
@@ -65,7 +65,7 @@
6565
"@types/jest": "^29.2.0",
6666
"@types/react-dom": "^18.0.9",
6767
"rimraf": "~3.0.0",
68-
"typedoc": "~0.23.25",
68+
"typedoc": "~0.24.1",
6969
"typescript": "~5.0.4"
7070
},
7171
"publishConfig": {

‎packages/debugger/package.json

+1-1
Original file line numberDiff line numberDiff line change
@@ -85,7 +85,7 @@
8585
"canvas": "^2.9.1",
8686
"jest": "^29.2.0",
8787
"rimraf": "~3.0.0",
88-
"typedoc": "~0.23.25",
88+
"typedoc": "~0.24.1",
8989
"typescript": "~5.0.4"
9090
},
9191
"publishConfig": {

‎packages/docmanager-extension/package.json

+1-1
Original file line numberDiff line numberDiff line change
@@ -58,7 +58,7 @@
5858
},
5959
"devDependencies": {
6060
"rimraf": "~3.0.0",
61-
"typedoc": "~0.23.25",
61+
"typedoc": "~0.24.1",
6262
"typescript": "~5.0.4"
6363
},
6464
"publishConfig": {

‎packages/docmanager/package.json

+1-1
Original file line numberDiff line numberDiff line change
@@ -63,7 +63,7 @@
6363
"@types/jest": "^29.2.0",
6464
"jest": "^29.2.0",
6565
"rimraf": "~3.0.0",
66-
"typedoc": "~0.23.25",
66+
"typedoc": "~0.24.1",
6767
"typescript": "~5.0.4"
6868
},
6969
"publishConfig": {

‎packages/docregistry/package.json

+1-1
Original file line numberDiff line numberDiff line change
@@ -65,7 +65,7 @@
6565
"@types/jest": "^29.2.0",
6666
"jest": "^29.2.0",
6767
"rimraf": "~3.0.0",
68-
"typedoc": "~0.23.25",
68+
"typedoc": "~0.24.1",
6969
"typescript": "~5.0.4"
7070
},
7171
"publishConfig": {

‎packages/extensionmanager-extension/package.json

+1-1
Original file line numberDiff line numberDiff line change
@@ -48,7 +48,7 @@
4848
},
4949
"devDependencies": {
5050
"rimraf": "~3.0.0",
51-
"typedoc": "~0.23.25",
51+
"typedoc": "~0.24.1",
5252
"typescript": "~5.0.4"
5353
},
5454
"publishConfig": {

‎packages/extensionmanager/package.json

+1-1
Original file line numberDiff line numberDiff line change
@@ -55,7 +55,7 @@
5555
"@types/semver": "^7.3.3",
5656
"jest": "^29.2.0",
5757
"rimraf": "~3.0.0",
58-
"typedoc": "~0.23.25",
58+
"typedoc": "~0.24.1",
5959
"typescript": "~5.0.4"
6060
},
6161
"publishConfig": {

‎packages/filebrowser-extension/package.json

+1-1
Original file line numberDiff line numberDiff line change
@@ -56,7 +56,7 @@
5656
},
5757
"devDependencies": {
5858
"rimraf": "~3.0.0",
59-
"typedoc": "~0.23.25",
59+
"typedoc": "~0.24.1",
6060
"typescript": "~5.0.4"
6161
},
6262
"publishConfig": {

‎packages/filebrowser/package.json

+1-1
Original file line numberDiff line numberDiff line change
@@ -68,7 +68,7 @@
6868
"@types/jest": "^29.2.0",
6969
"jest": "^29.2.0",
7070
"rimraf": "~3.0.0",
71-
"typedoc": "~0.23.25",
71+
"typedoc": "~0.24.1",
7272
"typescript": "~5.0.4"
7373
},
7474
"publishConfig": {

‎packages/fileeditor-extension/package.json

+1-1
Original file line numberDiff line numberDiff line change
@@ -69,7 +69,7 @@
6969
},
7070
"devDependencies": {
7171
"rimraf": "~3.0.0",
72-
"typedoc": "~0.23.25",
72+
"typedoc": "~0.24.1",
7373
"typescript": "~5.0.4"
7474
},
7575
"publishConfig": {

‎packages/fileeditor/package.json

+1-1
Original file line numberDiff line numberDiff line change
@@ -63,7 +63,7 @@
6363
"@types/jest": "^29.2.0",
6464
"jest": "^29.2.0",
6565
"rimraf": "~3.0.0",
66-
"typedoc": "~0.23.25",
66+
"typedoc": "~0.24.1",
6767
"typescript": "~5.0.4"
6868
},
6969
"publishConfig": {

‎packages/help-extension/package.json

+1-1
Original file line numberDiff line numberDiff line change
@@ -53,7 +53,7 @@
5353
},
5454
"devDependencies": {
5555
"rimraf": "~3.0.0",
56-
"typedoc": "~0.23.25",
56+
"typedoc": "~0.24.1",
5757
"typescript": "~5.0.4"
5858
},
5959
"publishConfig": {

‎packages/imageviewer-extension/package.json

+1-1
Original file line numberDiff line numberDiff line change
@@ -46,7 +46,7 @@
4646
},
4747
"devDependencies": {
4848
"rimraf": "~3.0.0",
49-
"typedoc": "~0.23.25",
49+
"typedoc": "~0.24.1",
5050
"typescript": "~5.0.4"
5151
},
5252
"publishConfig": {

0 commit comments

Comments
 (0)