misc changes

rmorshea · rmorshea · commit ef9b6e4e1668 · 2021-11-11T00:47:18.000-08:00
diff --git a/docs/source/creating-interfaces/dynamic-element-children.rst b/docs/source/creating-interfaces/dynamic-element-children.rst
@@ -1,4 +1,4 @@
-Dynamic Layout Structure
+Dynamic Element Children
 ========================
 
 Under construction :)
diff --git a/docs/source/creating-interfaces/index.rst b/docs/source/creating-interfaces/index.rst
@@ -8,19 +8,20 @@ Creating Interfaces
     your-first-component
     parametrizing-components
     conditional-rendering
-    dynamic-layout-structure
+    dynamic-element-children
 
 .. dropdown:: :octicon:`bookmark-fill;2em` What You'll Learn
     :color: info
     :animate: fade-in
 
     .. grid:: 2
 
-        .. grid-item-card:: :octicon:`mortar-board` Intro to HTML
+        .. grid-item-card:: :octicon:`mortar-board` HTML with IDOM
             :link: html-with-idom
             :link-type: doc
 
-            Learn how to construct HTML layouts with IDOM.
+            Learn how to construct HTML layouts with IDOM and the underlying data
+            structure we use to represent them.
 
         .. grid-item-card:: :octicon:`package` Your First Component
             :link: your-first-component
@@ -39,13 +40,15 @@ Creating Interfaces
             :link: conditional-rendering
             :link-type: doc
 
-            Use what you've learned so far to add conditional logic to your components.
+            Use what you've learned so far to render display different views depending
+            on a what a component's inputs are.
 
-        .. grid-item-card:: :octicon:`versions` Dynamic Layout Structure
-            :link: dynamic-layout-structure
+        .. grid-item-card:: :octicon:`versions` Dynamic Element Children
+            :link: dynamic-element-children
             :link-type: doc
 
-            Understand how IDOM keeps track of changing layout structures.
+            Understand how to correctly render using lists of child elements that
+            may change in length or order
 
 IDOM is a Python package for making user interfaces (UI). These interfaces are built
 from small elements of functionality like buttons text and images. IDOM allows you to
@@ -94,7 +97,9 @@ To recreate the same thing in IDOM you would write:
 
     :octicon:`book` Read More
     ^^^^^^^^^^^^^^^^^^^^^^^^^
-    Learn how to construct HTML layouts with IDOM.
+
+    Learn how to construct HTML layouts with IDOM and the underlying data structure we
+    use to represent them.
 
 
 Section 2: Your First Component
@@ -109,5 +114,5 @@ Section 4: Conditional Rendering
 --------------------------------
 
 
-Section 5: Dynamic Layout Structure
+Section 5: Dynamic Element Children
 -----------------------------------
diff --git a/docs/source/escape-hatches/writing-your-own-client.rst b/docs/source/escape-hatches/writing-your-own-client.rst
@@ -1,4 +1,4 @@
-Writing Your Own client
+Writing Your Own Client
 =======================
 
 Under construction :)
diff --git a/docs/source/getting-started/_static/idom-in-jupyterlab.gif b/docs/source/getting-started/_static/idom-in-jupyterlab.gif
diff --git a/docs/source/getting-started/index.rst b/docs/source/getting-started/index.rst
@@ -27,12 +27,16 @@ Getting Started
             See the ways that IDOM can be run with servers or be embedded in existing
             applications.
 
-The fastest way to get started with IDOM is to try it out in a Juptyer Notebook:
+The fastest way to get started with IDOM is to try it out in a Juptyer Notebook. If you
+want to use a Notebook to work through the examples shown in this documentation, you'll
+want to replace calls to ``idom.run(App)`` with a line at the end of each cell that
+constructs the ``App()`` in question. If that doesn't make sense, the introductory
+notebook linked below will demonstrate how to do this:
 
 .. card::
     :link: https://mybinder.org/v2/gh/idom-team/idom-jupyter/main?urlpath=lab/tree/notebooks/introduction.ipynb
 
-    .. image:: /_static/idom-in-jupyterlab.gif
+    .. image:: _static/idom-in-jupyterlab.gif
         :scale: 72%
         :align: center
 
@@ -75,6 +79,7 @@ For anything else, report your issue in IDOM's
 
     :octicon:`book` Read More
     ^^^^^^^^^^^^^^^^^^^^^^^^^
+
     Learn how IDOM can be installed in a variety of different ways - with different web
     servers and even in different frameworks.
 
@@ -97,5 +102,6 @@ code:
 
     :octicon:`book` Read More
     ^^^^^^^^^^^^^^^^^^^^^^^^^
+
     See the ways that IDOM can be run with servers or be embedded in existing
     applications.
diff --git a/docs/source/index.rst b/docs/source/index.rst
@@ -71,14 +71,15 @@ function.
 Learning IDOM
 -------------
 
-This documentation is broken up into chapters that introduce you to concepts step by
-step with detailed explanations and lots of examples. You should feel free to dive into
-any section that seems interesting. While each chapter assumes knowledge from those
-that came before, when you encounter a concept you're unfamiliar with you should look
-for links that will help direct you to the place where it was originally taught.
+This documentation is broken up into chapters and sections that introduce you to
+concepts step by step with detailed explanations and lots of examples. You should feel
+free to dive into any content that seems interesting. While each chapter assumes
+knowledge from those that came before, when you encounter a concept you're unfamiliar
+with you should look for links that will help direct you to the place where it was
+originally taught.
 
 
-Chapter 0 - :ref:`Getting Started`
+Chapter 1 - :ref:`Getting Started`
 -----------------------------------
 
 If you want to follow along with examples in the sections that follow, you'll want to
@@ -89,36 +90,60 @@ IDOM within a Jupyter Notebook, this is where you can learn how to do those thin
 
 .. grid:: 2
 
-    .. grid-item-card::
-        :link: getting-started/index.html#quick-install
+    .. grid-item::
 
         .. image:: _static/install-and-run-idom.gif
 
-    .. grid-item-card::
-        :link: getting-started/index.html
+    .. grid-item::
 
-        .. image:: _static/idom-in-jupyterlab.gif
+        .. image:: getting-started/_static/idom-in-jupyterlab.gif
 
+.. card::
+    :link: getting-started/index
+    :link-type: doc
 
-Chapter 1 - :ref:`Creating Interfaces`
+    :octicon:`book` Read More
+    ^^^^^^^^^^^^^^^^^^^^^^^^^
+
+    Learn how IDOM can be installed and run in a variety of different ways - with
+    different web servers and frameworks as well as being embedded into existing apps.
+
+
+Chapter 2 - :ref:`Creating Interfaces`
 --------------------------------------
 
-...
+IDOM is a Python package for making user interfaces (UI). These interfaces are built
+from small elements of functionality like buttons text and images. IDOM allows you to
+combine these elements into reusable, nestable :ref:`"components" <your first
+component>`. In the sections that follow you'll learn how these UI elements are created
+and organized into components. Then, you'll use components to customize and
+conditionally display more complex UIs.
+
+Some sort of examples here...
+
+.. card::
+    :link: creating-interfaces/index
+    :link-type: doc
+
+    :octicon:`book` Read More
+    ^^^^^^^^^^^^^^^^^^^^^^^^^
+
+    Learn stuff...
 
 
-Chapter 2 - :ref:`Adding Interactivity`
+Chapter 3 - :ref:`Adding Interactivity`
 ---------------------------------------
 
 ...
 
 
-Chapter 3 - :ref:`Managing State`
+Chapter 4 - :ref:`Managing State`
 ---------------------------------
 
 ...
 
 
-Chapter 4 - :ref:`Escape Hatches`
+Chapter 5 - :ref:`Escape Hatches`
 ---------------------------------
 
 ...
