Merge pull request #3674 from bollwyvl/gh-3656-follow-up

More docs updates
jupyter-widgets · Jan 28, 2023 · 0eea422 · 0eea422
2 parents 6f6156c + 0a29514
commit 0eea422
Show file tree

Hide file tree

Showing 25 changed files with 140 additions and 87 deletions.
diff --git a/.binder/README b/.binder/README
@@ -1,10 +1,10 @@
 This directory holds configuration files for https://mybinder.org/.
 
 The interactive notebooks can be accessed with this link:
-https://mybinder.org/v2/gh/jupyter-widgets/ipywidgets/master?filepath=docs/source/examples
+https://mybinder.org/v2/gh/jupyter-widgets/ipywidgets/main?filepath=docs/source/examples
 
-To check out a different version, just replace "master" with the desired
+To check out a different version, just replace `main` with the desired
 branch/tag name or commit hash.
 
 To use JupyterLab, use:
-https://mybinder.org/v2/gh/jupyter-widgets/ipywidgets/master?urlpath=lab/tree/docs/source/examples
+https://mybinder.org/v2/gh/jupyter-widgets/ipywidgets/main?urlpath=lab/tree/docs/source/examples
diff --git a/.github/workflows/binder-on-pr.yml b/.github/workflows/binder-on-pr.yml
@@ -18,7 +18,7 @@ jobs:
           script: |
             var PR_HEAD_USERREPO = process.env.PR_HEAD_USERREPO;
             var PR_HEAD_REF = process.env.PR_HEAD_REF;
-            github.issues.createComment({
+            github.rest.issues.createComment({
               issue_number: context.issue.number,
               owner: context.repo.owner,
               repo: context.repo.repo,

diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml
@@ -2,7 +2,7 @@ name: Build jupyterlab_widgets
 
 on:
   push:
-    branches: master
+    branches: main
   pull_request:
     branches: '*'
 

diff --git a/.github/workflows/devinstall.yml b/.github/workflows/devinstall.yml
@@ -2,7 +2,7 @@ name: Run the dev-install script
 
 on:
   push:
-    branches: master
+    branches: main
   pull_request:
     branches: '*'
 

diff --git a/.github/workflows/packaging.yml b/.github/workflows/packaging.yml
@@ -2,7 +2,8 @@ name: Packaging
 
 on:
   push:
-    branches: [master]
+    branches:
+      - main
   pull_request:
     branches: '*'
 

diff --git a/README.md b/README.md
@@ -2,13 +2,13 @@
 
 | Purpose                         | Badges                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
 | ------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| **Latest (master: future 8.0)** | [![Test Status](https://github.com/jupyter-widgets/ipywidgets/actions/workflows/tests.yml/badge.svg?query=branch%3Amaster)](https://github.com/jupyter-widgets/ipywidgets/actions?query=branch%3Amaster) [![Documentation Status: latest](https://img.shields.io/readthedocs/ipywidgets?logo=read-the-docs)](https://ipywidgets.readthedocs.io/en/latest/?badge=latest) [![Binder:master](https://mybinder.org/badge_logo.svg)](https://mybinder.org/v2/gh/jupyter-widgets/ipywidgets/master?urlpath=lab/tree/docs%2Fsource%2Fexamples)                                     |
+| **Latest (`main`: future 8.0)** | [![Test Status](https://github.com/jupyter-widgets/ipywidgets/actions/workflows/tests.yml/badge.svg?query=branch%3Amain)](https://github.com/jupyter-widgets/ipywidgets/actions?query=branch%3Amain) [![Documentation Status: latest](https://img.shields.io/readthedocs/ipywidgets?logo=read-the-docs)](https://ipywidgets.readthedocs.io/en/latest/?badge=latest) [![Binder:main](https://mybinder.org/badge_logo.svg)](https://mybinder.org/v2/gh/jupyter-widgets/ipywidgets/main?urlpath=lab/tree/docs%2Fsource%2Fexamples)                                             |
 | **Stable**                      | [![Version](https://img.shields.io/pypi/v/ipywidgets.svg?logo=pypi)](https://pypi.python.org/pypi/ipywidgets) [![Conda Version](https://img.shields.io/conda/vn/conda-forge/ipywidgets.svg?logo=conda-forge)](https://anaconda.org/conda-forge/ipywidgets) [![Documentation Status](https://img.shields.io/readthedocs/ipywidgets?logo=read-the-docs)](https://ipywidgets.readthedocs.io/en/stable/?badge=stable) [![Binder:7.x](https://mybinder.org/badge_logo.svg)](https://mybinder.org/v2/gh/jupyter-widgets/ipywidgets/7.x?urlpath=lab/tree/docs%2Fsource%2Fexamples) |
 | **Communication**               | [![Join the chat at https://gitter.im/ipython/ipywidgets](https://badges.gitter.im/Join%20Chat.svg)](https://gitter.im/jupyter-widgets/Lobby) [![Discourse](https://img.shields.io/badge/help_forum-discourse-blue?logo=discourse)](https://discourse.jupyter.org/c/widgets/46)                                                                                                                                                                                                                                                                                             |
 |                                 |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
 
 **ipywidgets**, also known as jupyter-widgets or simply widgets, are
-[interactive HTML widgets](https://github.com/jupyter-widgets/ipywidgets/blob/master/docs/source/examples/Index.ipynb)
+[interactive HTML widgets](https://github.com/jupyter-widgets/ipywidgets/blob/main/docs/source/examples/Index.ipynb)
 for Jupyter notebooks and the IPython kernel.
 
 Notebooks come alive when interactive widgets are used. Users gain control of
@@ -21,7 +21,7 @@ ipywidgets to your notebooks, and we're here to help you get started.
 ## Core Interactive Widgets
 
 The fundamental widgets provided by this library are called core interactive
-widgets. A [demonstration notebook](https://github.com/jupyter-widgets/ipywidgets/blob/master/docs/source/examples/Index.ipynb)
+widgets. A [demonstration notebook](https://github.com/jupyter-widgets/ipywidgets/blob/main/docs/source/examples/Index.ipynb)
 provides an overview of the core interactive widgets, including:
 
 - sliders
@@ -87,14 +87,14 @@ see the detailed [developer install](docs/source/dev_install.md) instructions.
 
 If you want to install ipywidgets from source, **you will need the
 [yarn](https://yarnpkg.com/) package manager version 1.2.1 or later**.
-To install the latest master version from the root directory of the source
+To install the latest `main` version from the root directory of the source
 code, run `dev-install.sh`. To only build the Python package enter
 `pip install -e .`.
 
 ## Usage
 
 See the [examples](docs/source/examples.md) section of the documentation. The widgets are being used in a variety of ways; some uses can be seen in these notebooks:
-[Demo notebook of interactive widgets](https://github.com/jupyter-widgets/ipywidgets/blob/master/docs/source/examples/Index.ipynb)
+[Demo notebook of interactive widgets](https://github.com/jupyter-widgets/ipywidgets/blob/main/docs/source/examples/Index.ipynb)
 
 ## Change log
 
@@ -106,13 +106,13 @@ Refer to change log for more detail.
 
 | ipywidgets | JupyterLab | [Classic Notebook](https://github.com/jupyter/notebook) | [nbclassic](https://github.com/jupyterlab/nbclassic) |
 | ---------- | :--------: | :-----------------------------------------------------: | :--------------------------------------------------: |
-| master     |            |                            -                            |                         TBD                          |
-| 7.6.3      |            |                                                         |                        0.2.6                         |
+| `main`     |            |                            -                            |                         TBD                          |
+| `7.6.3`    |            |                                                         |                        0.2.6                         |
 | **Legacy** |            |                                                         |                                                      |
-| 6.x        |            |                                                         |                          -                           |
-| 5.x        |            |                           4.2                           |                          -                           |
-| 4.1.x      |            |                           4.1                           |                          -                           |
-| 4.0.x      |            |                           4.0                           |                          -                           |
+| `6.x`      |            |                                                         |                          -                           |
+| `5.x`      |            |                           4.2                           |                          -                           |
+| `4.1.x`    |            |                           4.1                           |                          -                           |
+| `4.0.x`    |            |                           4.0                           |                          -                           |
 
 ## Contributing to ipywidgets
 

diff --git a/docs/lite/jupyter_lite_config.json b/docs/lite/jupyter_lite_config.json
@@ -5,11 +5,13 @@
       "Layout Templates\\.ipynb",
       "Variable Inspector\\.ipynb"
     ],
-    "contents": ["../source/examples"],
+    "contents": ["../source/examples"]
+  },
+  "PipliteAddon": {
     "piplite_urls": [
-      "../python/ipywidgets/dist",
-      "../python/widgetsnbextension/dist",
-      "../python/jupyterlab_widgets/dist"
+      "../../python/ipywidgets/dist",
+      "../../python/widgetsnbextension/dist",
+      "../../python/jupyterlab_widgets/dist"
     ]
   }
 }
diff --git a/docs/source/_static/theme.css b/docs/source/_static/theme.css
@@ -1,9 +1,31 @@
-.demo-sidebar .demo-title {
-  font-size: var(--pst-sidebar-header-font-size);
-  font-weight: var(--pst-sidebar-header-font-weight);
-  margin-bottom: 0.5rem;
-}
-
+/* index */
 table.indextable tr.cap {
   background-color: var(--pst-color-on-background) !important;
 }
+
+/* demo */
+#demo-sidebar {
+  margin: 0;
+}
+
+#demo-sidebar .demo-app {
+  display: inline;
+  display: flex;
+  flex-direction: row;
+  align-items: baseline;
+  flex-wrap: wrap;
+  margin: 0.75rem 0.25rem 0 0.25rem;
+}
+
+.demo-app > * {
+  flex: 1 auto;
+  white-space: nowrap;
+}
+
+#demo-sidebar .admonition-title::after {
+  display: none;
+}
+
+#demo-sidebar .admonition-title {
+  padding-left: 0.75rem;
+}
diff --git a/docs/source/_templates/demo.html b/docs/source/_templates/demo.html
@@ -1,41 +1,41 @@
-<div class="demo-sidebar">
-  <p class="demo-title" role="heading" aria-level="1">
-    Try Jupyter Widgets <strong>Now</strong>
+<div id="demo-sidebar" class="admonition warning">
+  <p class="demo-title admonition-title" role="heading" aria-level="1">
+    <img src="https://jupyterlite.readthedocs.io/en/latest/_static/icon.svg" width="16" />
+    Try Jupyter Widgets
   </p>
 
-  <div class="demo-app btn-group btn-group-toggle" data-toggle="buttons">
-    <label class="btn btn-secondary active">
+  <div class="demo-app">
+    <label title="Try Widgets in a multi-document UI">
       <input
         type="radio"
         name="demo-app"
         autocomplete="off"
         checked
-        title="Lab"
-        value="{{ pathto('try/lab/index') }}?path=Index.ipynb&path=Widget%20List.ipynb"
+        value="{{ pathto('try/lab/index') }}?path=Widget%20List.ipynb"
       >
       <i class="fas fa-flask"></i> Lab
     </label>
-    <label class="btn btn-secondary">
+    <label title="Try Widgets in a single-document UI">
       <input
         type="radio"
         name="demo-app"
-        title="Notebook"
-        value="{{ pathto('try/retro/index') }}?path=Index.ipynb&path=Widget%20List.ipynb"
+        autocomplete="off"
+        value="{{ pathto('try/retro/index') }}?path=Widget%20List.ipynb"
       >
       <i class="fas fa-book"></i> Notebook
     </label>
+    <a
+      href="{{ pathto('try/lab/index') }}?path=Widget%20List.ipynb"
+      class="btn btn-primary"
+      target="_blank"
+      title="Try Jupyter Widgets in your browser."
+      id="demo-button"
+    >
+      <i class="fas fa-play"></i>
+      Try Now
+    </a>
   </div>
 
-  <a
-    href="{{ pathto('try/lab/index') }}?path=Index.ipynb&path=Widget%20List.ipynb"
-    class="btn btn-primary"
-    target="_blank"
-    title="Try Jupyter Widgets in your browser."
-    id="demo-button"
-  >
-    <i class="fas fa-play"></i>
-    Try Now
-  </a>
 
   <script>$(function() {
     $('.demo-app input').on('change', (event) => {

diff --git a/docs/source/_templates/sidebar-nav-bs-index.html b/docs/source/_templates/sidebar-nav-bs-index.html
@@ -0,0 +1,24 @@
+<style>
+  #bd-docs-nav .toctree-toggle,
+  #bd-docs-nav .toctree-checkbox {
+    display: none;
+  }
+  #bd-docs-nav .toctree-l1 > a{
+    font-weight: bold;
+  }
+</style>
+
+<nav class="bd-links" id="bd-docs-nav" aria-label="{{ _('Documentation Contents') }}">
+  <div class="bd-toc-item navbar-nav">
+    <!-- Specify a startdepth of 0 instead of default of 1 -->
+    {{ generate_toctree_html(
+      "sidebar",
+      startdepth=0,
+      show_nav_level=4,
+      maxdepth=4,
+      collapse=False,
+      includehidden=True,
+      titles_only=False
+    ) }}
+  </div>
+</nav>
diff --git a/docs/source/changelog.md b/docs/source/changelog.md
@@ -447,7 +447,7 @@ If you are developing a custom widget or widget manager, here are some major cha
   - A custom serializer is given the widget instance as its second argument, and a custom deserializer is given the widget manager as its second argument.
   - The Javascript model `.id` attribute has been renamed to `.model_id` to avoid conflicting with the Backbone `.id` attribute. ([#1410](https://github.com/jupyter-widgets/ipywidgets/pull/1410))
 - Regarding widget managers and the syncing message protocol:
-  - The widget protocol was significantly overhauled. The new widget messaging protocol (version 2) is specified in the [version 2 protocol documentation](https://github.com/jupyter-widgets/ipywidgets/blob/master/jupyter-widgets-schema/messages.md).
+  - The widget protocol was significantly overhauled. The new widget messaging protocol (version 2) is specified in the [version 2 protocol documentation](https://github.com/jupyter-widgets/ipywidgets/blob/main/jupyter-widgets-schema/messages.md).
   - Widgets are now displayed with a `display_data` message instead of with a custom comm message. See the [ipywidgets](https://github.com/jupyter-widgets/ipywidgets/blob/20cd0f050090b1b19bb9657b8c3fa42ae384cfca/ipywidgets/widgets/widget.py#L656) implementation for an example. ([#1274](https://github.com/jupyter-widgets/ipywidgets/pull/1274))
   - Custom widget managers are now responsible completely for loading widget model and view classes. Widget managers should provide an output model and view class appropriate for their environment so that the `Output` widget works. ([#1313](https://github.com/jupyter-widgets/ipywidgets/pull/1313))
   - The widget manager `clear_state` method no longer has a `commlessOnly` argument. All models in the widget manager will be closed and cleared when `clear_state` is called. ([#1354](https://github.com/jupyter-widgets/ipywidgets/pull/1354))
@@ -459,7 +459,7 @@ Major user-visible changes in ipywidgets 6.0 include:
 - Rendering of Jupyter interactive widgets in various web contexts
 
   sphinx documentation: http://ipywidgets.readthedocs.io/en/latest/examples/Widget%20List.html
-  nbviewer: http://nbviewer.jupyter.org/github/jupyter-widgets/ipywidgets/blob/master/docs/source/examples/Widget%20List.ipynb
+  nbviewer: http://nbviewer.jupyter.org/github/jupyter-widgets/ipywidgets/blob/main/docs/source/examples/Widget%20List.ipynb
   Static web pages: http://jupyter.org/widgets
 
 - Addition of a DatePicker widget in the core widget collection.

diff --git a/docs/source/conf.py b/docs/source/conf.py
@@ -46,7 +46,6 @@ def setup(app):
 
 extensions = [
     'myst_nb',
-    'sphinx.ext.autosectionlabel',
     'sphinx.ext.autodoc',
     'sphinx.ext.autosummary',
     'sphinx.ext.intersphinx',
@@ -178,14 +177,20 @@ def setup(app):
     "doc_path": "docs",
     "github_repo": "ipywidgets",
     "github_user": "jupyter-widgets",
-    "github_version": "master",
+    "github_version": "main",
 }
 
 html_sidebars = {
+    "index": [
+        "demo.html",
+        "search-field.html",
+        "sidebar-nav-bs-index.html",
+        "sidebar-ethical-ads.html",
+    ],
     "**": [
         "search-field.html",
-        "demo.html",
         "sidebar-nav-bs.html",
+        "demo.html",
         "sidebar-ethical-ads.html",
     ]
 }

diff --git a/docs/source/contributing.md b/docs/source/contributing.md
@@ -2,5 +2,5 @@
 
 We appreciate contributions from the community.
 
-We follow the [IPython Contributing Guide](https://github.com/ipython/ipython/blob/master/CONTRIBUTING.md)
+We follow the [IPython Contributing Guide](https://github.com/ipython/ipython/blob/main/CONTRIBUTING.md)
 and [Jupyter Contributing Guides](https://jupyter.readthedocs.io/en/latest/contributor/content-contributor.html).
diff --git a/docs/source/dev_install.md b/docs/source/dev_install.md
@@ -12,7 +12,7 @@ To install ipywidgets from git, you will need:
 - the latest [Jupyter Notebook development release](https://github.com/jupyter/notebook/releases)
 
   - Everything in the ipywidgets repository is developed using Jupyter
-    notebook's master branch.
+    notebook's `main` branch.
   - If you want to have a copy of ipywidgets that works against a stable
     version of the notebook, checkout the appropriate tag.
   - See the

diff --git a/docs/source/dev_release.md b/docs/source/dev_release.md
@@ -1,7 +1,7 @@
 # Developer Release Procedure
 
 To release a new version of the widgets on PyPI and npm, first checkout the
-`master` branch and `cd` into the repo root.
+`main` branch and `cd` into the repo root.
 
 ```
 cd release
@@ -43,9 +43,9 @@ Commit the changes (don't forget to `git add` the new model spec file).
 
 ```
 # clean out all dirty files
-git checkout master
-git pull origin master
-git reset --hard origin/master
+git checkout main
+git pull origin main
+git reset --hard origin/main
 git clean -fdx
 yarn install
 yarn version
@@ -121,11 +121,11 @@ Using the above script, you can do:
 ./scripts/hashes python/jupyterlab_widgets/dist/*
 ```
 
-Commit the changes you've made above, and include the uploaded files hashes in the commit message. Tag the release if ipywidgets was released. Push to origin master (and include the tag in the push), e.g:
+Commit the changes you've made above, and include the uploaded files hashes in the commit message. Tag the release if ipywidgets was released. Push to origin `main` (and include the tag in the push), e.g:
 
 ```
 git tag 8.0.4
-git push origin master 8.0.4
+git push origin main 8.0.4
 ```
 
 Update conda-forge packages (if the requirements changed to ipywidgets, make sure to update widgetsnbextension first).
@@ -150,7 +150,7 @@ Here are some commands used to generate some of the statistics above.
 
 ```
 # merges since in 6.0.0, but not 7.0.0, which is a rough list of merged PRs
-git log --merges 6.0.0...master --pretty=oneline
+git log --merges 6.0.0...main --pretty=oneline
 
 # To really make sure we get all PRs, we could write a program that
 # pulled all of the PRs, examined a commit in each one, and did
@@ -164,11 +164,11 @@ git log --merges 6.0.0...master --pretty=oneline
 git show -s --format=%cd --date=short 6.0.0^{commit}
 
 # Non-merge commits in 7.0.0 not in any 6.x release
-git log --pretty=oneline --no-merges ^6.0.0 master | wc -l
+git log --pretty=oneline --no-merges ^6.0.0 main | wc -l
 
 # Authors of non-merge commits
-git shortlog -s  6.0.0..master --no-merges | cut -c8- | sort -f
+git shortlog -s  6.0.0..main --no-merges | cut -c8- | sort -f
 
 # New committers: authors unique in the 6.0.0..7.0.0 logs, but not in the 6.0.0 log
-comm -23 <(git shortlog -s -n 6.0.0..master --no-merges | cut -c8- | sort) <(git shortlog -s -n 6.0.0 --no-merges | cut -c8- | sort) | sort -f
+comm -23 <(git shortlog -s -n 6.0.0..main --no-merges | cut -c8- | sort) <(git shortlog -s -n 6.0.0 --no-merges | cut -c8- | sort) | sort -f
 ```