docs: Overhaul docs toolchain (#3673)

* start work on docs build, add ts metapackage, more verbose build output

* mostly-building docs

* start replacing nbsphinx meta

* work on nav, header refs

* clean up more warnings

* add autodoc

* more metadata

* linting

* update, deduplicate yarn.lock

* update some dev tools

* bump node build versin, top python version

* update typescript deps

* more tsconfig

* normalize build, actions

* normalize yarn/jlpm run and install

* update docs deps

* bump ui-test deps

* fix labextension invocation

* lint yaml

* add typedoc

* start reworking docs site structure and content

* apply prettier to markdown

* prettier spec

* hoist js api

* restore yarn cache

* more yarn cache

* add jupyterlab-myst to binder

* update screenshot

* disable theme switcher for now

* normalize more yarn invocations, update another screenshot

Author: bollwyvl

.binder/requirements.txt

@@ -1,5 +1,6 @@
 bqplot
 ipyleaflet
+jupyterlab-myst
 jupyterlab~=3.0
 matplotlib
 networkx

.github/ISSUE_TEMPLATE/bug_report.md

@@ -59,10 +59,11 @@ Paste the output from your browser Javascript console here.
 </details>
 
 ### If using JupyterLab
+
 - JupyterLab version:
 
 <details><summary>Installed Labextensions</summary>
 <pre>
 Paste the output from your command line running `jupyter labextension list`.
 </pre>
-</details>
+</details>

.github/ISSUE_TEMPLATE/custom_widget_issue.md

@@ -1,15 +1,15 @@
 ---
 name: Custom Widget
 about: Issues or questions related to developing a custom widget
-labels: "Custom Widget"
+labels: 'Custom Widget'
 ---
 
-<!-- 
+<!--
 If this is a:
 
 Bug Report: Please add the relevant pieces of information from the bug report template to this issue  (https://github.com/jupyterlab/jupyterlab/issues/new?template=bug_report.md)
 
 Question: Great! Thanks for asking here, since someone else will be able to find the answer more easily in the future. Please try to provide as much detail as you can about what you would like to accomplish and what you have tried.
 
-Feature Request: Please follow the template from https://github.com/jupyterlab/jupyterlab/issues/new?template=feature_request.md 
+Feature Request: Please follow the template from https://github.com/jupyterlab/jupyterlab/issues/new?template=feature_request.md
 -->

.github/ISSUE_TEMPLATE/documentation.md

@@ -17,7 +17,6 @@ If you are referencing an existing piece of documentation or example please prov
 * There is no example showing how to do [...]
 -->
 
-
 ### Suggested Improvement
 
 <!--

.github/dependabot.yml

@@ -8,9 +8,9 @@ version: 2
 # Ref https://github.com/dependabot/dependabot-core/issues/2521#issuecomment-863261500
 updates:
   - package-ecosystem: npm
-    directory: "/"
+    directory: '/'
     schedule:
-      interval: "daily"
+      interval: 'daily'
     open-pull-requests-limit: 0 # in case you don't want to enable version updates
     allow:
-      - dependency-type: "production"
+      - dependency-type: 'production'

.github/workflows/binder-on-pr.yml

@@ -5,26 +5,25 @@ on:
     types: [opened]
 
 permissions:
-  pull-requests:
-    write
+  pull-requests: write
 
 jobs:
   binder:
     runs-on: ubuntu-latest
     steps:
-    - name: comment on PR with Binder link
-      uses: actions/github-script@v1
-      with:
-        github-token: ${{secrets.GITHUB_TOKEN}}
-        script: |
-          var PR_HEAD_USERREPO = process.env.PR_HEAD_USERREPO;
-          var PR_HEAD_REF = process.env.PR_HEAD_REF;
-          github.issues.createComment({
-            issue_number: context.issue.number,
-            owner: context.repo.owner,
-            repo: context.repo.repo,
-            body: `[![Binder](https://mybinder.org/badge_logo.svg)](https://mybinder.org/v2/gh/${PR_HEAD_USERREPO}/${PR_HEAD_REF}?urlpath=lab/tree/docs/source/examples/) :point_left: Launch a binder notebook on branch _${PR_HEAD_USERREPO}/${PR_HEAD_REF}_`
-          })
-      env:
-        PR_HEAD_REF: ${{ github.event.pull_request.head.ref }}
-        PR_HEAD_USERREPO: ${{ github.event.pull_request.head.repo.full_name }}
+      - name: comment on PR with Binder link
+        uses: actions/github-script@v6
+        with:
+          github-token: ${{secrets.GITHUB_TOKEN}}
+          script: |
+            var PR_HEAD_USERREPO = process.env.PR_HEAD_USERREPO;
+            var PR_HEAD_REF = process.env.PR_HEAD_REF;
+            github.issues.createComment({
+              issue_number: context.issue.number,
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              body: `[![Binder](https://mybinder.org/badge_logo.svg)](https://mybinder.org/v2/gh/${PR_HEAD_USERREPO}/${PR_HEAD_REF}?urlpath=lab/tree/docs/source/examples/) :point_left: Launch a binder notebook on branch _${PR_HEAD_USERREPO}/${PR_HEAD_REF}_`
+            })
+        env:
+          PR_HEAD_REF: ${{ github.event.pull_request.head.ref }}
+          PR_HEAD_USERREPO: ${{ github.event.pull_request.head.repo.full_name }}

.github/workflows/build.yml

@@ -10,42 +10,66 @@ jobs:
   build:
     runs-on: ubuntu-latest
     steps:
-    - name: Checkout
-      uses: actions/checkout@v1
-    - name: Install node
-      uses: actions/setup-node@v3
-      with:
-        node-version: '14'
-        cache: 'yarn'
-    - name: Install Python
-      uses: actions/setup-python@v1
-      with:
-        python-version: '3.8'
-        architecture: 'x64'
-    - name: Cache pip on Linux
-      uses: actions/cache@v1
-      if: startsWith(runner.os, 'Linux')
-      with:
-        path: ~/.cache/pip
-        key: ${{ runner.os }}-pip-${{ matrix.python }}-${{ hashFiles('**/requirements.txt') }}
-        restore-keys: |
-          ${{ runner.os }}-pip-${{ matrix.python }}
-
-    - name: Install dependencies
-      run: |
-        python -m pip install jupyterlab~=3.0 jupyter_packaging~=0.10
-    - name: Build the extension
-      run: |
-        pushd python/ipywidgets
-        pip install .
-        popd
-        jlpm install
-        jlpm run build
-        pushd python/jupyterlab_widgets
-        pwd
-        pip install -e .
-        jupyter labextension develop . --overwrite
-        popd
-        jupyter labextension list
-
-        python -m jupyterlab.browser_check
+      - name: Checkout
+        uses: actions/checkout@v3
+
+      - name: Install node
+        uses: actions/setup-node@v3
+        with:
+          node-version: '18'
+          cache: yarn
+
+      - name: Install Python
+        uses: actions/setup-python@v4
+        with:
+          python-version: '3.8'
+          architecture: 'x64'
+
+      - name: Cache pip on Linux
+        uses: actions/cache@v3
+        if: startsWith(runner.os, 'Linux')
+        with:
+          path: ~/.cache/pip
+          key: ${{ runner.os }}-pip-${{ matrix.python }}-${{ hashFiles('**/requirements.txt') }}
+          restore-keys: |
+            ${{ runner.os }}-pip-${{ matrix.python }}
+
+      - name: Install build dependencies
+        run: |
+          python -m pip install jupyterlab~=3.0 jupyter_packaging~=0.10
+
+      - name: Install node dependencies
+        run: |
+          jlpm
+
+      - name: Build node packages
+        run: |
+          jlpm build
+
+      - name: Install jupyterlab_widgets
+        run: |
+          cd python/jupyterlab_widgets
+          pip install -vv -e . --no-deps
+
+      - name: Install widgetsnbextension
+        run: |
+          cd python/widgetsnbextension
+          pip install -vv -e . --no-deps
+
+      - name: Install ipywidgets
+        run: |
+          cd python/ipywidgets
+          pip install -vv . --no-deps
+
+      - name: Install development extension
+        run: |
+          cd python/jupyterlab_widgets
+          jupyter labextension develop . --overwrite
+
+      - name: List labextensions
+        run: |
+          jupyter labextension list
+
+      - name: Run JupyterLab browser check
+        run: |
+          python -m jupyterlab.browser_check

.github/workflows/devinstall.yml

@@ -10,34 +10,34 @@ jobs:
   devinstall:
     runs-on: ubuntu-latest
     steps:
-    - name: Checkout
-      uses: actions/checkout@v1
-    - name: Install node
-      uses: actions/setup-node@v3
-      with:
-        node-version: '14'
-        cache: 'yarn'
-    - name: Install Python
-      uses: actions/setup-python@v1
-      with:
-        python-version: '3.8'
-        architecture: 'x64'
-    - name: Cache pip on Linux
-      uses: actions/cache@v1
-      if: startsWith(runner.os, 'Linux')
-      with:
-        path: ~/.cache/pip
-        key: ${{ runner.os }}-pip-${{ matrix.python }}-${{ hashFiles('**/requirements.txt') }}
-        restore-keys: |
-          ${{ runner.os }}-pip-${{ matrix.python }}
+      - name: Checkout
+        uses: actions/checkout@v3
+      - name: Install node
+        uses: actions/setup-node@v3
+        with:
+          node-version: '18'
+          cache: yarn
+      - name: Install Python
+        uses: actions/setup-python@v4
+        with:
+          python-version: '3.8'
+          architecture: 'x64'
+      - name: Cache pip on Linux
+        uses: actions/cache@v3
+        if: startsWith(runner.os, 'Linux')
+        with:
+          path: ~/.cache/pip
+          key: ${{ runner.os }}-pip-${{ matrix.python }}-${{ hashFiles('**/requirements.txt') }}
+          restore-keys: |
+            ${{ runner.os }}-pip-${{ matrix.python }}
 
-    - name: Install dependencies
-      run: |
-        python -m pip install notebook jupyterlab~=3.0 jupyter_packaging~=0.10
-    - name: Run the dev-install script
-      run: |
-        ./dev-install.sh
-        jupyter nbextension list
-        jupyter labextension list
+      - name: Install dependencies
+        run: |
+          python -m pip install notebook jupyterlab~=3.0 jupyter_packaging~=0.10
+      - name: Run the dev-install script
+        run: |
+          ./dev-install.sh
+          jupyter nbextension list
+          jupyter labextension list
 
-        python -m jupyterlab.browser_check
+          python -m jupyterlab.browser_check

.github/workflows/lint.yml

@@ -8,14 +8,14 @@ jobs:
     runs-on: ubuntu-latest
 
     steps:
-    - uses: actions/checkout@v2
-    - name: Install node
-      uses: actions/setup-node@v3
-      with:
-        node-version: '14'
-        cache: 'yarn'
-    - name: yarn install, integrity, lint
-      run: |
-        yarn install --frozen-lockfile
-        yarn run integrity
-        yarn run lint:check
+      - uses: actions/checkout@v3
+      - name: Install node
+        uses: actions/setup-node@v3
+        with:
+          node-version: '18'
+          cache: yarn
+      - name: yarn install, integrity, lint
+        run: |
+          yarn --frozen-lockfile
+          yarn integrity
+          yarn lint:check