Add tutorial page for Mark properties with cross-referencing from rel…

…evant docstrings (#2989)

* Add basic components for property documentation and crosslinking

* Add color property documentation

* Add example images for all properties

* Add coordinate properties

doc/conf.py

@@ -14,6 +14,8 @@
 import sys
 import time
 import seaborn
+from seaborn._core.properties import PROPERTIES
+
 sys.path.insert(0, os.path.abspath('sphinxext'))
 
 
@@ -103,6 +105,11 @@
 
 """  # noqa
 
+rst_epilog += "\n".join([
+    f".. |{key}| replace:: :ref:`{key} <{val.__class__.__name__.lower()}_property>`"
+    for key, val in PROPERTIES.items()
+])
+
 # -- Options for HTML output -------------------------------------------------
 
 # The theme to use for HTML and HTML Help pages.  See the documentation for

doc/tutorial.rst

@@ -91,6 +91,30 @@ API Overview
 
           tutorial/error_bars
 
+Objects interface
+-----------------
+
+.. grid:: 1
+  :gutter: 2
+
+  .. grid-item-card::
+
+    .. grid:: 2
+
+      .. grid-item::
+        :columns: 4
+
+        .. image:: ./tutorial/properties_files/properties_3_0.png
+          :target: ./tutorial/properties.html
+
+      .. grid-item::
+        :columns: 8
+
+        .. toctree::
+          :maxdepth: 2
+
+          tutorial/properties
+
 
 Plotting functions
 ------------------

seaborn/_core/plot.py

@@ -120,7 +120,8 @@ def build_plot_signature(cls):
     cls.__signature__ = new_sig
 
     known_properties = textwrap.fill(
-        ", ".join(PROPERTIES), 78, subsequent_indent=" " * 8,
+        ", ".join([f"|{p}|" for p in PROPERTIES]),
+        width=78, subsequent_indent=" " * 8,
     )
 
     if cls.__doc__ is not None:  # support python -OO mode

seaborn/_marks/area.py

@@ -14,6 +14,7 @@
     MappableStyle,
     resolve_properties,
     resolve_color,
+    document_properties,
 )
 
 
@@ -85,6 +86,7 @@ def _legend_artist(self, variables, value, scales):
         )
 
 
+@document_properties
 @dataclass
 class Area(AreaBase, Mark):
     """
@@ -134,6 +136,7 @@ def _postprocess_artist(self, artist, ax, orient):
         artist.sticky_edges[val_idx][:] = (0, np.inf)
 
 
+@document_properties
 @dataclass
 class Band(AreaBase, Mark):
     """

seaborn/_marks/bar.py

@@ -14,6 +14,7 @@
     MappableStyle,
     resolve_properties,
     resolve_color,
+    document_properties
 )
 from seaborn.external.version import Version
 
@@ -102,6 +103,7 @@ def _legend_artist(
         return artist
 
 
+@document_properties
 @dataclass
 class Bar(BarBase):
     """
@@ -171,6 +173,7 @@ def _plot(self, split_gen, scales, orient):
             ax.add_container(container)
 
 
+@document_properties
 @dataclass
 class Bars(BarBase):
     """

seaborn/_marks/base.py

@@ -1,5 +1,6 @@
 from __future__ import annotations
 from dataclasses import dataclass, fields, field
+import textwrap
 from typing import Any, Callable, Union
 from collections.abc import Generator
 
@@ -286,9 +287,23 @@ def visible(x, axis=None):
     # (i.e. set fillalpha to 0 when fill=False)
 
 
-class MultiMark(Mark):
-
-    # TODO implement this as a way to wrap multiple marks (e.g. line and ribbon)
-    # It should be fairly lightweight, the main thing is to expose the union
-    # of each mark's parameters and then to call them sequentially in _plot.
-    pass
+def document_properties(mark):
+
+    properties = [f.name for f in fields(mark) if isinstance(f.default, Mappable)]
+    text = [
+        "",
+        "    This mark defines the following properties:",
+        textwrap.fill(
+            ", ".join([f"|{p}|" for p in properties]),
+            width=78, initial_indent=" " * 8, subsequent_indent=" " * 8,
+        ),
+    ]
+
+    docstring_lines = mark.__doc__.split("\n")
+    new_docstring = "\n".join([
+        *docstring_lines[:2],
+        *text,
+        *docstring_lines[2:],
+    ])
+    mark.__doc__ = new_docstring
+    return mark

seaborn/_marks/dot.py

@@ -14,6 +14,7 @@
     MappableStyle,
     resolve_properties,
     resolve_color,
+    document_properties,
 )
 
 from typing import TYPE_CHECKING
@@ -23,7 +24,6 @@
     from seaborn._core.scales import Scale
 
 
-@dataclass
 class DotBase(Mark):
 
     def _resolve_paths(self, data):
@@ -103,6 +103,7 @@ def _legend_artist(
         )
 
 
+@document_properties
 @dataclass
 class Dot(DotBase):
     """
@@ -156,6 +157,7 @@ def _resolve_properties(self, data, scales):
         return resolved
 
 
+@document_properties
 @dataclass
 class Dots(DotBase):
     """

seaborn/_marks/line.py

@@ -13,10 +13,12 @@
     MappableColor,
     resolve_properties,
     resolve_color,
+    document_properties,
 )
 from seaborn.external.version import Version
 
 
+@document_properties
 @dataclass
 class Path(Mark):
     """
@@ -115,6 +117,7 @@ def _handle_capstyle(self, kws, vals):
             kws["dash_capstyle"] = capstyle
 
 
+@document_properties
 @dataclass
 class Line(Path):
     """
@@ -133,6 +136,7 @@ class Line(Path):
     _sort: ClassVar[bool] = True
 
 
+@document_properties
 @dataclass
 class Paths(Mark):
     """
@@ -221,6 +225,7 @@ def _legend_artist(self, variables, value, scales):
         )
 
 
+@document_properties
 @dataclass
 class Lines(Paths):
     """
@@ -238,6 +243,7 @@ class Lines(Paths):
     _sort: ClassVar[bool] = True
 
 
+@document_properties
 @dataclass
 class Range(Paths):
     """