From b996fa45d66c94266b97475eab0723b1841436cf Mon Sep 17 00:00:00 2001
From: dsmedia <63077097+dsmedia@users.noreply.github.com>
Date: Tue, 13 Aug 2024 08:07:09 -0400
Subject: [PATCH] docs: Explain the title `frame` attribute (#3537)

* docs: Adds frame attribute.
explains what is meant in this case by 'group', expands on meaning of other title attributes, and changes doc link reference from "customization" to "configuration", where the chart title properties are discussed.
Resolves #3402

* Shorten line length

* Make a clearer distinction of what happens when the title frame is changed

* Fix typo

---------

Co-authored-by: Joel Ostblom <joel.ostblom@gmail.com>
---
 doc/user_guide/customization.rst | 31 +++++++++++++++++++++++++++++--
 1 file changed, 29 insertions(+), 2 deletions(-)

diff --git a/doc/user_guide/customization.rst b/doc/user_guide/customization.rst
index 1bd3ff658..c068d62e3 100644
--- a/doc/user_guide/customization.rst
+++ b/doc/user_guide/customization.rst
@@ -180,7 +180,9 @@ The subtitle can run to two lines by passing a list where each list item is a li
        color="source:N"
    )
 
-The ``Title`` object can also configure a number of other attributes, e.g., the position of the title and subtitle (see see :ref:`user-guide-customization` for details).
+The ``Title`` object can also configure a number of other attributes,
+e.g., to ``anchor`` it to the ``'start'`` (left) of the chart,
+and to ``orient`` it at the ``'bottom'`` of the chart (see :ref:`user-guide-configuration` for more options).
 
 .. altair-plot::
 
@@ -188,7 +190,7 @@ The ``Title`` object can also configure a number of other attributes, e.g., the
       iowa,
       title=alt.Title(
           "Iowa's green energy boom",
-          subtitle=["A growing share of the state's energy", "has come from renewable sources"],
+          subtitle="A growing share of the state's energy has come from renewable sources",
           anchor='start',
           orient='bottom',
           offset=20
@@ -199,6 +201,31 @@ The ``Title`` object can also configure a number of other attributes, e.g., the
        color="source:N"
    )
 
+In the chart above,
+you can see that the title is positioned all the way to the left,
+so that it lines up with the label on the y-axis.
+You can align the title to the axis line instead
+by setting the reference ``frame`` for the anchor position
+to be relative to the ``'group'`` (i.e. the data portion of the chart, excluding labels and titles).
+
+
+.. altair-plot::
+
+   alt.Chart(
+      iowa,
+      title=alt.Title(
+          "Iowa's green energy boom",
+          subtitle=["A growing share of the state's energy has come from", "renewable sources"],
+          anchor='start',
+          frame='group',
+          orient='bottom',
+          offset=20
+      )
+   ).mark_area().encode(
+       x="year:T",
+       y=alt.Y("net_generation:Q").stack("normalize"),
+       color="source:N"
+   )
 
 Adjusting Axis Limits
 ---------------------