Update nextgen docs

mwaskom · Jul 14, 2022 · 08e1d5f · 08e1d5f
1 parent 4cbffa9
commit 08e1d5f
Show file tree

Hide file tree

Showing 5 changed files with 83 additions and 34 deletions.
diff --git a/doc/nextgen/api.rst b/doc/nextgen/api.rst
@@ -22,6 +22,8 @@ Plot interface
     Plot.facet
     Plot.pair
     Plot.configure
+    Plot.limit
+    Plot.label
     Plot.on
     Plot.plot
     Plot.save
@@ -36,6 +38,7 @@ Marks
 
     Area
     Bar
+    Bars
     Dot
     Line
     Lines

diff --git a/doc/nextgen/conf.py b/doc/nextgen/conf.py
@@ -61,14 +61,16 @@
 
 html_theme_options = {
     "show_prev_next": False,
-    "page_sidebar_items": [],
+    # "page_sidebar_items": [],
 }
 
 html_context = {
    # other contexts
    "default_mode": "light"
 }
 
+html_show_sourcelink = False
+
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,
 # so a file named "default.css" will overwrite the builtin "default.css".
@@ -77,10 +79,13 @@
 html_logo = "_static/logo.svg"
 
 html_sidebars = {
-    # "**": [],
-    "demo": ["page-toc"]
+    "index": [],
+    "demo": ["page-toc.html"],
 }
 
+html_context= {
+    "default_mode": "light",
+}
 
 # -- Intersphinx ------------------------------------------------
 

diff --git a/doc/nextgen/demo.ipynb b/doc/nextgen/demo.ipynb
@@ -637,7 +637,7 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "so.Plot(planets, x=\"distance\").add(so.Bar(), so.Hist()).scale(x=\"log\")"
+    "so.Plot(planets, x=\"distance\").add(so.Bars(), so.Hist()).scale(x=\"log\")"
    ]
   },
   {
@@ -660,7 +660,7 @@
     "        planets, x=\"distance\",\n",
     "        color=(planets[\"number\"] > 1).rename(\"multiple\")\n",
     "    )\n",
-    "    .add(so.Bar(), so.Hist(), so.Dodge())\n",
+    "    .add(so.Bars(), so.Hist(), so.Dodge())\n",
     "    .scale(x=\"log\", color=so.Nominal())\n",
     ")"
    ]
@@ -821,6 +821,34 @@
     "Importantly, there's no distinction between \"axes-level\" and \"figure-level\" here. Any kind of plot can be faceted or paired by adding a method call to the `Plot` definition, without changing anything else about how you are creating the figure."
    ]
   },
+  {
+   "cell_type": "markdown",
+   "id": "9933b5fa-5b1a-4e05-a4d3-b2142e5337ef",
+   "metadata": {},
+   "source": [
+    "------\n",
+    "\n",
+    "## Customization\n",
+    "\n",
+    "This API is less developed than other aspects of the new interface, but it will be possible to customize various aspects of the plot through the seaborn interface, without dropping down to matplotlib:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "61c2e0e2-1df5-466d-a17e-0bc64d21f9f9",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "(\n",
+    "    so.Plot(tips, \"day\", \"total_bill\", color=\"sex\")\n",
+    "    .add(so.Bar(), so.Agg(), so.Dodge())\n",
+    "    .scale(y=so.Continuous().label(like=\"${x:.0f}\"))\n",
+    "    .label(x=str.capitalize, y=\"Total bill\", color=None)\n",
+    "    .limit(y=(0, 28))\n",
+    ")"
+   ]
+  },
   {
    "cell_type": "markdown",
    "id": "d1eff6ab-84dd-4b32-9923-3d29fb43a209",

diff --git a/doc/nextgen/index.ipynb b/doc/nextgen/index.ipynb
@@ -40,13 +40,21 @@
    "id": "c76dbb00-20ee-4508-bca3-76a4763e5640",
    "metadata": {},
    "source": [
-    "## Testing the alpha release\n",
+    "## Testing the pre-release\n",
     "\n",
-    "If you're interested, please install the alpha and kick the tires. It is very far from complete, so expect some rough edges and instability! But feedback will be very helpful in pushing this towards a more stable broad release:\n",
+    "If you're interested, please install the pre-release and kick the tires. It is still a work in progress, so expect some rough edges and instability! But feedback will be very helpful in pushing this towards a more stable broad release:\n",
     "\n",
-    "    pip install https://github.com/mwaskom/seaborn/archive/refs/tags/v0.12.0a0.tar.gz\n",
+    "    pip install --pre seaborn"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "f194cc12-856a-4261-8717-462c290c9e51",
+   "metadata": {},
+   "source": [
+    "## Preview components\n",
     "\n",
-    "The documentation is still a work in progress, but there's a reasonably thorough demo of the main parts, and some basic API documentation for the existing classes."
+    "The formal documentation is still a work-in-progress, so this preview serves as an introduction and reference for testing. There's a reasonably thorough demo of the main components and some basic API documentation for the existing classes:"
    ]
   },
   {
@@ -57,8 +65,8 @@
     ".. toctree::\n",
     "    :maxdepth: 1\n",
     "\n",
-    "    demo\n",
-    "    api"
+    "    Demonstration <demo>\n",
+    "    API Overview <api>"
    ]
   },
   {
@@ -76,7 +84,7 @@
     "\n",
     "So the new interface is designed to provide a more comprehensive experience, such that all of the steps involved in the creation of a reasonably-customized plot can be accomplished in the same way. And the compositional nature of the objects provides much more flexibility than currently exists in seaborn with a similar level of abstraction: this lets you focus on *what* you want to show rather than *how* to show it.\n",
     "\n",
-    "One will note that the result looks a bit (a lot?) like ggplot. That's not unintentional, but the goal is also *not* to \"port ggplot2 to Python\". (If that's what you're looking for, check out the very nice [plotnine](https://plotnine.readthedocs.io/en/stable/) package). There is an immense amount of wisdom in the grammar of graphics and in its particular implementation as ggplot2. But, as languages, R and Python are just too different for idioms from one to feel natural when translated literally into the other. So while I have taken much inspiration from ggplot (along with vega-lite, d3, and other great libraries), I've also made plenty of choices differently, for better or for worse."
+    "One will note that the result looks a bit (a lot?) like ggplot. That's not unintentional: while the original seaborn interface was never explicitly intended to implement a grammar of graphics, the redesign is. But the goal is also *not* to \"port ggplot2 to Python\". (If that's what you're looking for, check out the very nice [plotnine](https://plotnine.readthedocs.io/en/stable/) package). I do think that ggplot2 gets a lot right, especially its approach to layering. But, as languages, R and Python are just too different for idioms from one to feel natural when translated literally into the other. So while I have taken much inspiration from ggplot (along with vega-lite, d3, and other great libraries), I've also made plenty of choices differently, for better or for worse."
    ]
   },
   {

diff --git a/doc/nextgen/index.rst b/doc/nextgen/index.rst
@@ -37,27 +37,31 @@ with the new interface:
 
 
 
-Testing the alpha release
--------------------------
+Testing the pre-release
+-----------------------
 
-If you’re interested, please install the alpha and kick the tires. It is
-very far from complete, so expect some rough edges and instability! But
-feedback will be very helpful in pushing this towards a more stable
-broad release:
+If you’re interested, please install the pre-release and kick the tires.
+It is still a work in progress, so expect some rough edges and
+instability! But feedback will be very helpful in pushing this towards a
+more stable broad release:
 
 ::
 
-   pip install https://github.com/mwaskom/seaborn/archive/refs/tags/v0.12.0a0.tar.gz
+   pip install --pre seaborn
 
-The documentation is still a work in progress, but there’s a reasonably
-thorough demo of the main parts, and some basic API documentation for
-the existing classes.
+Preview components
+------------------
+
+The formal documentation is still a work-in-progress, so this preview
+serves as an introduction and reference for testing. There’s a
+reasonably thorough demo of the main components and some basic API
+documentation for the existing classes:
 
 .. toctree::
     :maxdepth: 1
 
-    demo
-    api
+    Demonstration <demo>
+    API Overview <api>
 
 Background and goals
 --------------------
@@ -91,14 +95,15 @@ currently exists in seaborn with a similar level of abstraction: this
 lets you focus on *what* you want to show rather than *how* to show it.
 
 One will note that the result looks a bit (a lot?) like ggplot. That’s
-not unintentional, but the goal is also *not* to “port ggplot2 to
-Python”. (If that’s what you’re looking for, check out the very nice
-`plotnine <https://plotnine.readthedocs.io/en/stable/>`__ package).
-There is an immense amount of wisdom in the grammar of graphics and in
-its particular implementation as ggplot2. But, as languages, R and
-Python are just too different for idioms from one to feel natural when
-translated literally into the other. So while I have taken much
-inspiration from ggplot (along with vega-lite, d3, and other great
-libraries), I’ve also made plenty of choices differently, for better or
-for worse.
+not unintentional: while the original seaborn interface was never
+explicitly intended to implement a grammar of graphics, the redesign is.
+But the goal is also *not* to “port ggplot2 to Python”. (If that’s what
+you’re looking for, check out the very nice
+`plotnine <https://plotnine.readthedocs.io/en/stable/>`__ package). I do
+think that ggplot2 gets a lot right, especially its approach to
+layering. But, as languages, R and Python are just too different for
+idioms from one to feel natural when translated literally into the
+other. So while I have taken much inspiration from ggplot (along with
+vega-lite, d3, and other great libraries), I’ve also made plenty of
+choices differently, for better or for worse.