Assorted small doc updates (#3502)

* Assorted, small documentation updates

* Add v0.12 to archive selector

* Further updates

doc/_templates/layout.html

@@ -14,6 +14,7 @@
             Archive
         </a>
         <div class="dropdown-menu dropdown-menu-right" aria-labelledby="dropdownMenuLink">
+          <a class="dropdown-item" href="/archive/0.12/index.html">v0.12</a>
           <a class="dropdown-item" href="/archive/0.11/index.html">v0.11</a>
           <a class="dropdown-item" href="/archive/0.10/index.html">v0.10</a>
           <a class="dropdown-item" href="/archive/0.9/index.html">v0.9</a>

doc/_tutorial/categorical.ipynb

@@ -133,7 +133,7 @@
    "cell_type": "raw",
    "metadata": {},
    "source": [
-    "Unlike with numerical data, it is not always obvious how to order the levels of the categorical variable along its axis. In general, the seaborn categorical plotting functions try to infer the order of categories from the data. If your data have a pandas ``Categorical`` datatype, then the default order of the categories can be set there. If the variable passed to the categorical axis looks numerical, the levels will be sorted. But the data are still treated as categorical and drawn at ordinal positions on the categorical axes (specifically, at 0, 1, ...) even when numbers are used to label them:"
+    "Unlike with numerical data, it is not always obvious how to order the levels of the categorical variable along its axis. In general, the seaborn categorical plotting functions try to infer the order of categories from the data. If your data have a pandas ``Categorical`` datatype, then the default order of the categories can be set there. If the variable passed to the categorical axis looks numerical, the levels will be sorted. But, by default, the data are still treated as categorical and drawn at ordinal positions on the categorical axes (specifically, at 0, 1, ...) even when numbers are used to label them:"
    ]
   },
   {
@@ -145,6 +145,22 @@
     "sns.catplot(data=tips.query(\"size != 3\"), x=\"size\", y=\"total_bill\")"
    ]
   },
+  {
+   "cell_type": "raw",
+   "metadata": {},
+   "source": [
+    "As of v0.13.0, all categorical plotting functions have a `native_scale` parameter, which can be set to `True` when you want to use numeric or datetime data for categorical grouping without changing the underlying data properties: "
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "sns.catplot(data=tips.query(\"size != 3\"), x=\"size\", y=\"total_bill\", native_scale=True)"
+   ]
+  },
   {
    "cell_type": "raw",
    "metadata": {},
@@ -205,7 +221,7 @@
    "cell_type": "raw",
    "metadata": {},
    "source": [
-    "When adding a ``hue`` semantic, the box for each level of the semantic variable is moved along the categorical axis so they don't overlap:"
+    "When adding a ``hue`` semantic, the box for each level of the semantic variable is made narrower and shifted along the categorical axis:"
    ]
   },
   {
@@ -221,7 +237,7 @@
    "cell_type": "raw",
    "metadata": {},
    "source": [
-    "This behavior is called \"dodging\" and is turned on by default because it is assumed that the semantic variable is nested within the main categorical variable. If that's not the case, you can disable the dodging:"
+    "This behavior is called \"dodging\", and it is controlled by the `dodge` parameter. By default (as of v0.13.0), elements dodge only if they would otherwise overlap:"
    ]
   },
   {
@@ -231,10 +247,7 @@
    "outputs": [],
    "source": [
     "tips[\"weekend\"] = tips[\"day\"].isin([\"Sat\", \"Sun\"])\n",
-    "sns.catplot(\n",
-    "    data=tips, x=\"day\", y=\"total_bill\", hue=\"weekend\",\n",
-    "    kind=\"box\", dodge=False,\n",
-    ")"
+    "sns.catplot(data=tips, x=\"day\", y=\"total_bill\", hue=\"weekend\", kind=\"box\")"
    ]
   },
   {

doc/_tutorial/data_structure.ipynb

@@ -19,7 +19,7 @@
     "As a data visualization library, seaborn requires that you provide it with data. This chapter explains the various ways to accomplish that task. Seaborn supports several different dataset formats, and most functions accept data represented with objects from the `pandas <https://pandas.pydata.org/>`_ or `numpy <https://numpy.org/>`_ libraries as well as built-in Python types like lists and dictionaries. Understanding the usage patterns associated with these different options will help you quickly create useful visualizations for nearly any dataset.\n",
     "\n",
     ".. note::\n",
-    "   As of current writing (v0.11.0), the full breadth of options covered here are supported by only a subset of the modules in seaborn (namely, the :ref:`relational <relational_api>` and :ref:`distribution <distribution_api>` modules). The other modules offer much of the same flexibility, but have some exceptions (e.g., :func:`catplot` and :func:`lmplot` are limited to long-form data with named variables). The data-ingest code will be standardized over the next few release cycles, but until that point, be mindful of the specific documentation for each function if it is not doing what you expect with your dataset."
+    "   As of current writing (v0.13.0), the full breadth of options covered here are supported by most, but not all, of the functions in seaborn. Namely, a few older functinos (e.g., :func:`lmplot` and :func:`regplot`) anre more limited in what they accept."
    ]
   },
   {

doc/faq.rst

@@ -122,9 +122,9 @@ Several :ref:`seaborn functions <categorical_api>` are referred to as "categoric
 
 At the time these functions were written, matplotlib did not have any direct support for non-numeric data types. So seaborn internally builds a mapping from unique values in the data to 0-based integer indexes, which is what it passes to matplotlib. If your data are strings, that's great, and it more-or-less matches how `matplotlib now handles <https://matplotlib.org/stable/gallery/lines_bars_and_markers/categorical_variables.html>`_ string-typed data.
 
-But a potential gotcha is that these functions *always do this*, even if both the x and y variables are numeric. This gives rise to a number of confusing behaviors, especially when mixing categorical and non-categorical plots (e.g., a combo bar-and-line plot).
+But a potential gotcha is that these functions *always do this by default*, even if both the x and y variables are numeric. This gives rise to a number of confusing behaviors, especially when mixing categorical and non-categorical plots (e.g., a combo bar-and-line plot).
 
-The v0.12 release added a `native_scale` parameter to :func:`stripplot` and :func:`swarmplot`, which provides control over this behavior. It will be rolled out to other categorical functions in future releases. But the current behavior will almost certainly remain the default, so this is an important API wrinkle to understand.
+The v0.13 release added a `native_scale` parameter which provides control over this behavior. It is `False` by default, but setting it to `True` will preserve the original properties of the data used for categorical grouping.
 
 Specifying data
 ---------------

doc/whatsnew/v0.13.0.rst

@@ -1,5 +1,5 @@
-v0.13.0 (Unreleased)
---------------------
+v0.13.0 (September 2023)
+------------------------
 
 This is a major release with a number of important new features and changes. The highlight is a major overhaul to seaborn's categorical plotting functions, providing them with many new capabilities and better aligning their API with the rest of the library. There is also provisional support for alternate dataframe libraries like `polars <https://www.pola.rs>`_, a new theme and display configuration system for :class:`objects.Plot`, and many smaller bugfixes and enhancements.
 
@@ -34,8 +34,8 @@ Two related idiosyncratic color specifications are deprecated, but they will con
 
 Finally, like other seaborn functions, the default palette now depends on the variable type, and a sequential palette will be used with numeric data. To retain the previous behavior, pass the name of a qualitative palette (e.g., `palette="deep"` for seaborn's default). Accordingly, the functions have gained a parameter to control numeric color mappings (`hue_norm`).
 
-Other features, enhancements, and changes to categorical plots
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Other features, enhancements, and changes
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 The following updates apply to multiple categorical functions.
 

examples/grouped_violinplots.py

@@ -5,13 +5,12 @@
 _thumb: .44, .47
 """
 import seaborn as sns
-sns.set_theme(style="whitegrid")
+sns.set_theme(style="dark")
 
 # Load the example tips dataset
 tips = sns.load_dataset("tips")
 
 # Draw a nested violinplot and split the violins for easier comparison
 sns.violinplot(data=tips, x="day", y="total_bill", hue="smoker",
-               split=True, inner="quart", linewidth=1,
-               palette={"Yes": "b", "No": ".85"})
-sns.despine(left=True)
+               split=True, inner="quart", fill=False,
+               palette={"Yes": "g", "No": ".35"})