made changes to LabIcon docs requested by reviewer

docs/source/developer/ui_components.rst

@@ -1,3 +1,12 @@
+.. raw:: html
+
+   <!--
+   THIS FILE IS AUTOGENERATED, DO NOT EDIT
+
+   Instead, make changes to docs sources in `packages/ui-components/docs`,
+   then run "jlpm docs:init" to refresh the built docs
+   -->
+
 .. _ui_components:
 
 Reusing JupyterLab UI
@@ -22,79 +31,6 @@ current JupyterLab theme.
 ``LabIcon`` is the icon class used by JupyterLab, and is part of the new
 icon system introduced in JupyterLab v2.0.
 
-Background
-~~~~~~~~~~
-
-Icon handling in Jupyterlab
-^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-Pre JupyterLab version 2.0, most icons were created using the icons-as-css-background
-pattern:
-
--  Set up the icon’s svg as a ``background-image`` in CSS:
-
-   .. code:: css
-
-      /* CSS */
-
-      .jp-FooIcon {
-        background-image: url('path-to-your/foo.svg');
-      }
-
--  Add the icon to the DOM by constructing an otherwise empty DOM node
-   with the appropriate class:
-
-   .. code:: typescript
-
-      // typescript
-
-      const e = document.createElement('div');
-      e.className = 'jp-FooIcon';
-      document.body.append(e);
-
-What you end up with is a single DOM node that has the “foo” icon as a
-background image.
-
-Post jlab-2.0, nearly all icons in core are now created using
-`LabIcon <https://github.com/jupyterlab/jupyterlab/blob/f0153e0258b32674c9aec106383ddf7b618cebab/packages/ui-components/src/icon/labicon.tsx>`__
-and the icons-as-inline-svg pattern:
-
--  Construct a new instance of LabIcon from the icon’s name and svg:
-
-   .. code:: typescript
-
-      // typescript
-
-      // svgstr is the raw contents of an icon's svg file
-      export const fooIcon = new LabIcon({
-        name: 'barpkg:foo',
-        svgstr: '<svg>...</svg>'
-      });
-
--  Add the icon to the DOM using the appropriate property of your
-   LabIcon instance (either LabIcon.element() to directly create a DOM
-   node, or LabIcon.react to get the icon as a react component):
-
-   .. code:: typescript
-
-      // typescript
-
-      const e = fooIcon.element();
-      document.body.append(e);
-
-What you end up with is a DOM node (by default a ‘div’) that has an
-inline svg node as a child.
-
-``background-image`` vs inline svg
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-The big limitation of the old icon-as-css-background pattern is that svg
-images rendered as ``background-image`` are invisible to CSS. On the
-other hand, an icon rendered as an inline svg node is fully exposed to
-the CSS. This allows us to dynamicly change icon styling as needed
-simply by modifying our CSS. Most importantly, this allows us to recolor
-icons according to Jupyterlab’s current theme.
-
 How JupyterLab handles icons
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
@@ -273,7 +209,7 @@ forth.
    <li>jp-icon-accent0: <svg width="16" viewBox="0 0 1 1"><rect width="1" height="1" fill="#fff"/><title>#fff</title></svg> / <svg width="16" viewBox="0 0 1 1"><rect width="1" height="1" fill="#111"/><title>#111</title></svg></li>
    <li>jp-icon-accent1: <svg width="16" viewBox="0 0 1 1"><rect width="1" height="1" fill="#fff"/><title>#fff</title></svg> / <svg width="16" viewBox="0 0 1 1"><rect width="1" height="1" fill="#212121"/><title>#212121</title></svg></li>
    <li>jp-icon-accent2: <svg width="16" viewBox="0 0 1 1"><rect width="1" height="1" fill="#eee"/><title>#eee</title></svg> / <svg width="16" viewBox="0 0 1 1"><rect width="1" height="1" fill="#424242"/><title>#424242</title></svg></li>
-   <li>jp-icon-accent3: <svg width="16" viewBox="0 0 1 1"><rect width="1" height="1" fill="#bdbdbd"/><title>#bdbdbd</title></svg> / <svg width="16" viewBox="0 0 1 1"><rect width="1" height="1" fill="#616161"/><title>#616161bdbdbd</title></svg></li>
+   <li>jp-icon-accent3: <svg width="16" viewBox="0 0 1 1"><rect width="1" height="1" fill="#bdbdbd"/><title>#bdbdbd</title></svg> / <svg width="16" viewBox="0 0 1 1"><rect width="1" height="1" fill="#616161"/><title>#616161</title></svg></li>
    <li>jp-icon-accent4: <svg width="16" viewBox="0 0 1 1"><rect width="1" height="1" fill="#757575"/><title>#757575</title></svg> / <svg width="16" viewBox="0 0 1 1"><rect width="1" height="1" fill="#757575"/><title>#757575</title></svg></li>
    </ul>
 
@@ -335,3 +271,76 @@ that needs to contrast with the background should be annotated with a
      <rect class="jp-icon-accent0" fill="#fff" height="18" width="2" x="11" y="3" transform="rotate(315, 12, 12)"/>
      <rect class="jp-icon-accent0" fill="#fff" height="18" width="2" x="11" y="3" transform="rotate(45, 12, 12)"/>
    </svg>
+
+Background
+~~~~~~~~~~
+
+Icon handling in Jupyterlab
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Pre JupyterLab 2.0, most icons were created using the icons-as-css-background
+pattern:
+
+-  Set up the icon’s svg as a ``background-image`` in CSS:
+
+   .. code:: css
+
+      /* CSS */
+
+      .jp-FooIcon {
+        background-image: url('path-to-your/foo.svg');
+      }
+
+-  Add the icon to the DOM by constructing an otherwise empty DOM node
+   with the appropriate class:
+
+   .. code:: typescript
+
+      // typescript
+
+      const e = document.createElement('div');
+      e.className = 'jp-FooIcon';
+      document.body.append(e);
+
+What you end up with is a single DOM node that has the “foo” icon as a
+background image.
+
+Post JupyterLab 2.0, nearly all icons in core are now created using
+`LabIcon <https://github.com/jupyterlab/jupyterlab/blob/f0153e0258b32674c9aec106383ddf7b618cebab/packages/ui-components/src/icon/labicon.tsx>`__
+and the icons-as-inline-svg pattern:
+
+-  Construct a new instance of LabIcon from the icon’s name and svg:
+
+   .. code:: typescript
+
+      // typescript
+
+      // svgstr is the raw contents of an icon's svg file
+      export const fooIcon = new LabIcon({
+        name: 'barpkg:foo',
+        svgstr: '<svg>...</svg>'
+      });
+
+-  Add the icon to the DOM using the appropriate property of your
+   LabIcon instance (either LabIcon.element() to directly create a DOM
+   node, or LabIcon.react to get the icon as a react component):
+
+   .. code:: typescript
+
+      // typescript
+
+      const e = fooIcon.element();
+      document.body.append(e);
+
+What you end up with is a DOM node (by default a ‘div’) that has an
+inline svg node as a child.
+
+``background-image`` vs inline svg
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The big limitation of the old icon-as-css-background pattern is that svg
+images rendered as ``background-image`` are invisible to CSS. On the
+other hand, an icon rendered as an inline svg node is fully exposed to
+the CSS. This allows us to dynamicly change icon styling as needed
+simply by modifying our CSS. Most importantly, this allows us to recolor
+icons according to Jupyterlab’s current theme.

package.json

@@ -51,6 +51,7 @@
     "create:theme": "node buildutils/lib/create-theme.js",
     "deduplicate": "jlpm yarn-deduplicate -s fewer --fail",
     "docs": "lerna run docs",
+    "docs:init": "lerna run docs:init",
     "eslint": "eslint --ext .js,.jsx,.ts,.tsx --fix .",
     "eslint:check": "eslint --ext .js,.jsx,.ts,.tsx .",
     "get:dependency": "node buildutils/lib/get-dependency.js",

packages/ui-components/README.md

@@ -1,3 +1,10 @@
+<!--
+THIS FILE IS AUTOGENERATED, DO NOT EDIT
+
+Instead, make changes to docs sources in `packages/ui-components/docs`,
+then run "jlpm docs:init" to refresh the built docs
+-->
+
 # @jupyterlab/ui-components
 
 The
@@ -15,76 +22,6 @@ JupyterLab theme.
 `LabIcon` is the icon class used by JupyterLab, and is part of the new
 icon system introduced in JupyterLab v2.0.
 
-## Background
-
-### Icon handling in Jupyterlab
-
-Pre jlab-2.0, most icons were created using the icons-as-css-background
-pattern:
-
-- Set up the icon’s svg as a `background-image` in CSS:
-
-  ```css
-  /* CSS */
-
-  .jp-FooIcon {
-    background-image: url('path-to-your/foo.svg');
-  }
-  ```
-
-- Add the icon to the DOM by constructing an otherwise empty DOM node
-  with the appropriate class:
-
-  ```typescript
-  // typescript
-
-  const e = document.createElement('div');
-  e.className = 'jp-FooIcon';
-  document.body.append(e);
-  ```
-
-What you end up with is a single DOM node that has the “foo” icon as a
-background image.
-
-Post jlab-2.0, nearly all icons in core are now created using
-[LabIcon](https://github.com/jupyterlab/jupyterlab/blob/f0153e0258b32674c9aec106383ddf7b618cebab/packages/ui-components/src/icon/labicon.tsx)
-and the icons-as-inline-svg pattern:
-
-- Construct a new instance of LabIcon from the icon’s name and svg:
-
-  ```typescript
-  // typescript
-
-  // svgstr is the raw contents of an icon's svg file
-  export const fooIcon = new LabIcon({
-    name: 'barpkg:foo',
-    svgstr: '<svg>...</svg>'
-  });
-  ```
-
-- Add the icon to the DOM using the appropriate property of your
-  LabIcon instance (either LabIcon.element() to directly create a DOM
-  node, or LabIcon.react to get the icon as a react component):
-
-  ```typescript
-  // typescript
-
-  const e = fooIcon.element();
-  document.body.append(e);
-  ```
-
-What you end up with is a DOM node (by default a ‘div’) that has an
-inline svg node as a child.
-
-### `background-image` vs inline svg
-
-The big limitation of the old icon-as-css-background pattern is that svg
-images rendered as `background-image` are invisible to CSS. On the other
-hand, an icon rendered as an inline svg node is fully exposed to the
-CSS. This allows us to dynamicly change icon styling as needed simply by
-modifying our CSS. Most importantly, this allows us to recolor icons
-according to Jupyterlab’s current theme.
-
 ## How JupyterLab handles icons
 
 The @jupyterlab/ui-components package provides icons to the rest of
@@ -247,7 +184,7 @@ forth.
 <li>jp-icon-accent0: <svg width="16" viewBox="0 0 1 1"><rect width="1" height="1" fill="#fff"/><title>#fff</title></svg> / <svg width="16" viewBox="0 0 1 1"><rect width="1" height="1" fill="#111"/><title>#111</title></svg></li>
 <li>jp-icon-accent1: <svg width="16" viewBox="0 0 1 1"><rect width="1" height="1" fill="#fff"/><title>#fff</title></svg> / <svg width="16" viewBox="0 0 1 1"><rect width="1" height="1" fill="#212121"/><title>#212121</title></svg></li>
 <li>jp-icon-accent2: <svg width="16" viewBox="0 0 1 1"><rect width="1" height="1" fill="#eee"/><title>#eee</title></svg> / <svg width="16" viewBox="0 0 1 1"><rect width="1" height="1" fill="#424242"/><title>#424242</title></svg></li>
-<li>jp-icon-accent3: <svg width="16" viewBox="0 0 1 1"><rect width="1" height="1" fill="#bdbdbd"/><title>#bdbdbd</title></svg> / <svg width="16" viewBox="0 0 1 1"><rect width="1" height="1" fill="#616161"/><title>#616161bdbdbd</title></svg></li>
+<li>jp-icon-accent3: <svg width="16" viewBox="0 0 1 1"><rect width="1" height="1" fill="#bdbdbd"/><title>#bdbdbd</title></svg> / <svg width="16" viewBox="0 0 1 1"><rect width="1" height="1" fill="#616161"/><title>#616161</title></svg></li>
 <li>jp-icon-accent4: <svg width="16" viewBox="0 0 1 1"><rect width="1" height="1" fill="#757575"/><title>#757575</title></svg> / <svg width="16" viewBox="0 0 1 1"><rect width="1" height="1" fill="#757575"/><title>#757575</title></svg></li>
 </ul>
 
@@ -323,3 +260,73 @@ _rendered icon:_
   <rect class="jp-icon-accent0" fill="#fff" height="18" width="2" x="11" y="3" transform="rotate(315, 12, 12)"/>
   <rect class="jp-icon-accent0" fill="#fff" height="18" width="2" x="11" y="3" transform="rotate(45, 12, 12)"/>
 </svg>
+
+## Background
+
+### Icon handling in Jupyterlab
+
+Pre JupyterLab 2.0, most icons were created using the
+icons-as-css-background pattern:
+
+- Set up the icon’s svg as a `background-image` in CSS:
+
+  ```css
+  /* CSS */
+
+  .jp-FooIcon {
+    background-image: url('path-to-your/foo.svg');
+  }
+  ```
+
+- Add the icon to the DOM by constructing an otherwise empty DOM node
+  with the appropriate class:
+
+  ```typescript
+  // typescript
+
+  const e = document.createElement('div');
+  e.className = 'jp-FooIcon';
+  document.body.append(e);
+  ```
+
+What you end up with is a single DOM node that has the “foo” icon as a
+background image.
+
+Post JupyterLab 2.0, nearly all icons in core are now created using
+[LabIcon](https://github.com/jupyterlab/jupyterlab/blob/f0153e0258b32674c9aec106383ddf7b618cebab/packages/ui-components/src/icon/labicon.tsx)
+and the icons-as-inline-svg pattern:
+
+- Construct a new instance of LabIcon from the icon’s name and svg:
+
+  ```typescript
+  // typescript
+
+  // svgstr is the raw contents of an icon's svg file
+  export const fooIcon = new LabIcon({
+    name: 'barpkg:foo',
+    svgstr: '<svg>...</svg>'
+  });
+  ```
+
+- Add the icon to the DOM using the appropriate property of your
+  LabIcon instance (either LabIcon.element() to directly create a DOM
+  node, or LabIcon.react to get the icon as a react component):
+
+  ```typescript
+  // typescript
+
+  const e = fooIcon.element();
+  document.body.append(e);
+  ```
+
+What you end up with is a DOM node (by default a ‘div’) that has an
+inline svg node as a child.
+
+### `background-image` vs inline svg
+
+The big limitation of the old icon-as-css-background pattern is that svg
+images rendered as `background-image` are invisible to CSS. On the other
+hand, an icon rendered as an inline svg node is fully exposed to the
+CSS. This allows us to dynamicly change icon styling as needed simply by
+modifying our CSS. Most importantly, this allows us to recolor icons
+according to Jupyterlab’s current theme.

packages/ui-components/docs/build.sh

@@ -24,11 +24,11 @@ pushd $SOURCE > /dev/null
 pandoc $SOURCE/labicon.rst -f rst -t rst --wrap=preserve --shift-heading-level-by=1 -o $BUILD/labicon.rst
 
 # make the README.md at package root
-pandoc $SOURCE/README.rst -f rst -t gfm -o $PKG_ROOT/README.md    #--resource-path=$SOURCE
+pandoc $SOURCE/generated_warning.rst $SOURCE/README.rst -f rst -t gfm -o $PKG_ROOT/README.md    #--resource-path=$SOURCE
 echo "built $PKG_ROOT/README.md"
 
 # make the dev docs for the monorepo's docs
-pandoc $SOURCE/ui_components.rst -f rst -t rst --wrap=preserve -o $MONOREPO_DEVDOC/ui_components.rst
+pandoc $SOURCE/generated_warning.rst $SOURCE/ui_components.rst -f rst -t rst --wrap=preserve -o $MONOREPO_DEVDOC/ui_components.rst
 echo "built $MONOREPO_DEVDOC/ui_components.rst"
 
 popd > /dev/null

packages/ui-components/docs/source/generated_warning.rst

@@ -0,0 +1,8 @@
+.. raw:: html
+
+   <!--
+   THIS FILE IS AUTOGENERATED, DO NOT EDIT
+
+   Instead, make changes to docs sources in `packages/ui-components/docs`,
+   then run "jlpm docs:init" to refresh the built docs
+   -->

packages/ui-components/docs/source/labicon.rst

@@ -4,79 +4,6 @@
 ``LabIcon`` is the icon class used by JupyterLab, and is part of the new
 icon system introduced in JupyterLab v2.0.
 
-Background
-----------
-
-Icon handling in Jupyterlab
-~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-Pre jlab-2.0, most icons were created using the icons-as-css-background
-pattern:
-
--  Set up the icon’s svg as a ``background-image`` in CSS:
-
-   .. code:: css
-
-      /* CSS */
-
-      .jp-FooIcon {
-        background-image: url('path-to-your/foo.svg');
-      }
-
--  Add the icon to the DOM by constructing an otherwise empty DOM node
-   with the appropriate class:
-
-   .. code:: typescript
-
-      // typescript
-
-      const e = document.createElement('div');
-      e.className = 'jp-FooIcon';
-      document.body.append(e);
-
-What you end up with is a single DOM node that has the “foo” icon as a
-background image.
-
-Post jlab-2.0, nearly all icons in core are now created using
-`LabIcon <https://github.com/jupyterlab/jupyterlab/blob/f0153e0258b32674c9aec106383ddf7b618cebab/packages/ui-components/src/icon/labicon.tsx>`__
-and the icons-as-inline-svg pattern:
-
--  Construct a new instance of LabIcon from the icon’s name and svg:
-
-   .. code:: typescript
-
-      // typescript
-
-      // svgstr is the raw contents of an icon's svg file
-      export const fooIcon = new LabIcon({
-        name: 'barpkg:foo',
-        svgstr: '<svg>...</svg>'
-      });
-
--  Add the icon to the DOM using the appropriate property of your
-   LabIcon instance (either LabIcon.element() to directly create a DOM
-   node, or LabIcon.react to get the icon as a react component):
-
-   .. code:: typescript
-
-      // typescript
-
-      const e = fooIcon.element();
-      document.body.append(e);
-
-What you end up with is a DOM node (by default a ‘div’) that has an
-inline svg node as a child.
-
-``background-image`` vs inline svg
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-The big limitation of the old icon-as-css-background pattern is that svg
-images rendered as ``background-image`` are invisible to CSS. On the
-other hand, an icon rendered as an inline svg node is fully exposed to
-the CSS. This allows us to dynamicly change icon styling as needed
-simply by modifying our CSS. Most importantly, this allows us to recolor
-icons according to Jupyterlab’s current theme.
-
 How JupyterLab handles icons
 ----------------------------
 
@@ -255,7 +182,7 @@ forth.
    <li>jp-icon-accent0: <svg width="16" viewBox="0 0 1 1"><rect width="1" height="1" fill="#fff"/><title>#fff</title></svg> / <svg width="16" viewBox="0 0 1 1"><rect width="1" height="1" fill="#111"/><title>#111</title></svg></li>
    <li>jp-icon-accent1: <svg width="16" viewBox="0 0 1 1"><rect width="1" height="1" fill="#fff"/><title>#fff</title></svg> / <svg width="16" viewBox="0 0 1 1"><rect width="1" height="1" fill="#212121"/><title>#212121</title></svg></li>
    <li>jp-icon-accent2: <svg width="16" viewBox="0 0 1 1"><rect width="1" height="1" fill="#eee"/><title>#eee</title></svg> / <svg width="16" viewBox="0 0 1 1"><rect width="1" height="1" fill="#424242"/><title>#424242</title></svg></li>
-   <li>jp-icon-accent3: <svg width="16" viewBox="0 0 1 1"><rect width="1" height="1" fill="#bdbdbd"/><title>#bdbdbd</title></svg> / <svg width="16" viewBox="0 0 1 1"><rect width="1" height="1" fill="#616161"/><title>#616161bdbdbd</title></svg></li>
+   <li>jp-icon-accent3: <svg width="16" viewBox="0 0 1 1"><rect width="1" height="1" fill="#bdbdbd"/><title>#bdbdbd</title></svg> / <svg width="16" viewBox="0 0 1 1"><rect width="1" height="1" fill="#616161"/><title>#616161</title></svg></li>
    <li>jp-icon-accent4: <svg width="16" viewBox="0 0 1 1"><rect width="1" height="1" fill="#757575"/><title>#757575</title></svg> / <svg width="16" viewBox="0 0 1 1"><rect width="1" height="1" fill="#757575"/><title>#757575</title></svg></li>
    </ul>
 
@@ -317,3 +244,76 @@ that needs to contrast with the background should be annotated with a
      <rect class="jp-icon-accent0" fill="#fff" height="18" width="2" x="11" y="3" transform="rotate(315, 12, 12)"/>
      <rect class="jp-icon-accent0" fill="#fff" height="18" width="2" x="11" y="3" transform="rotate(45, 12, 12)"/>
    </svg>
+
+Background
+----------
+
+Icon handling in Jupyterlab
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Pre JupyterLab 2.0, most icons were created using the icons-as-css-background
+pattern:
+
+-  Set up the icon’s svg as a ``background-image`` in CSS:
+
+   .. code:: css
+
+      /* CSS */
+
+      .jp-FooIcon {
+        background-image: url('path-to-your/foo.svg');
+      }
+
+-  Add the icon to the DOM by constructing an otherwise empty DOM node
+   with the appropriate class:
+
+   .. code:: typescript
+
+      // typescript
+
+      const e = document.createElement('div');
+      e.className = 'jp-FooIcon';
+      document.body.append(e);
+
+What you end up with is a single DOM node that has the “foo” icon as a
+background image.
+
+Post JupyterLab 2.0, nearly all icons in core are now created using
+`LabIcon <https://github.com/jupyterlab/jupyterlab/blob/f0153e0258b32674c9aec106383ddf7b618cebab/packages/ui-components/src/icon/labicon.tsx>`__
+and the icons-as-inline-svg pattern:
+
+-  Construct a new instance of LabIcon from the icon’s name and svg:
+
+   .. code:: typescript
+
+      // typescript
+
+      // svgstr is the raw contents of an icon's svg file
+      export const fooIcon = new LabIcon({
+        name: 'barpkg:foo',
+        svgstr: '<svg>...</svg>'
+      });
+
+-  Add the icon to the DOM using the appropriate property of your
+   LabIcon instance (either LabIcon.element() to directly create a DOM
+   node, or LabIcon.react to get the icon as a react component):
+
+   .. code:: typescript
+
+      // typescript
+
+      const e = fooIcon.element();
+      document.body.append(e);
+
+What you end up with is a DOM node (by default a ‘div’) that has an
+inline svg node as a child.
+
+``background-image`` vs inline svg
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The big limitation of the old icon-as-css-background pattern is that svg
+images rendered as ``background-image`` are invisible to CSS. On the
+other hand, an icon rendered as an inline svg node is fully exposed to
+the CSS. This allows us to dynamicly change icon styling as needed
+simply by modifying our CSS. Most importantly, this allows us to recolor
+icons according to Jupyterlab’s current theme.