Add tooltip attribute to description widgets #1864

docs/source/dev_install.md

@@ -68,6 +68,14 @@ permissions on npm and pip related install directories are correct.
 
     - Try reinstalling ipywidgets
 
+Updating widget model specification
+-----------------------------------
+
+To update the widget model specification with changes, do something like this in the repo root:
+```
+python ./packages/schema/generate-spec.py > packages/schema/jupyterwidgetmodels.latest.md
+```
+
 Releasing new versions
 ----------------------
 

docs/source/dev_release.md

@@ -4,6 +4,26 @@ Developer Release Procedure
 To release a new version of the widgets on PyPI and npm, first checkout master
 and cd into the repo root.
 
+### Fix the widget spec
+
+If there were changes in the widget model specification (i.e., any change made
+to any widget attributes), we need to update the model specification version and
+record the documented attributes.
+
+First, update the relevant model specification versions. For example, the commit https://github.com/jupyter-widgets/ipywidgets/commit/fca6f355605dc9e04062ce0eec4a7acbb5632ae2 updated the controls model version. We follow the semver spec for model version numbers, so model changes that are backwards-incompatible should be major version bumps, while backwards-compatible additions should be minor version bumps.
+
+Next, regenerate the model spec with the new version numbers by doing something like this in the repository root directory:
+```
+python ./packages/schema/generate-spec.py > packages/schema/jupyterwidgetmodels.latest.md
+```
+
+Copy `packages/schema/jupyterwidgetmodels.latest.md` to an appropriately-named
+markdown file (see the existing model spec files in that directory for the
+naming convention). This documents the widget model specification for a specific ipywidget
+release.
+
+Commit the changes (don't forget to `git add` the new model spec file).
+
 ### Publish the npm modules
 
 ```

ipywidgets/widgets/widget_description.py

@@ -21,6 +21,7 @@ class DescriptionWidget(DOMWidget, CoreWidget):
     """Widget that has a description label to the side."""
     _model_name = Unicode('DescriptionModel').tag(sync=True)
     description = Unicode('', help="Description of the control.").tag(sync=True)
+    description_tooltip = Unicode(None, allow_none=True, help="Tooltip for the description (defaults to description).").tag(sync=True)
     style = InstanceDict(DescriptionStyle, help="Styling customizations").tag(sync=True, **widget_serialization)
 
     def _repr_keys(self):

packages/controls/src/widget_description.ts

@@ -43,6 +43,7 @@ class DescriptionModel extends DOMWidgetModel {
             _view_module_version: JUPYTER_CONTROLS_VERSION,
             _model_module_version: JUPYTER_CONTROLS_VERSION,
             description: '',
+            description_tooltip: null,
         };
     }
 }
@@ -56,6 +57,7 @@ class DescriptionView extends DOMWidgetView {
         this.label.style.display = 'none';
 
         this.listenTo(this.model, 'change:description', this.updateDescription);
+        this.listenTo(this.model, 'change:description_tooltip', this.updateDescription);
         this.updateDescription();
     }
 
@@ -65,14 +67,19 @@ class DescriptionView extends DOMWidgetView {
 
     updateDescription() {
         let description = this.model.get('description');
+        let description_tooltip = this.model.get('description_tooltip');
+        if (description_tooltip === null) {
+            description_tooltip = description;
+        }
+
         if (description.length === 0) {
             this.label.style.display = 'none';
         } else {
             this.label.innerHTML = description;
             this.typeset(this.label);
             this.label.style.display = '';
         }
-        this.label.title = description;
+        this.label.title = description_tooltip;
     }
 
     label: HTMLLabelElement;