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 <[email protected]>
vega · Aug 13, 2024 · b996fa4 · b996fa4
1 parent 95f5d31
commit b996fa4
Showing 1 changed file with 29 additions and 2 deletions.
diff --git a/doc/user_guide/customization.rst b/doc/user_guide/customization.rst
@@ -180,15 +180,17 @@ 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::
 
    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"],
+          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
 ---------------------