BUG - Add --pst-color-heading fallback (#2082)

Nick pointed in
#2058 (comment)
that the `--pst-heading-color` variable is used by folks to customise
the headings colour (this was the colour variable before
#2058 which brought
this in line with our naming convention `--pst-color-heading`).

This change effectively renders the use of `--pst-heading-color`
useless, so this PR adds a fallback mechanism for this variable.

I also added a note about `--pst-color-heading` being our preferred
variable.
This is not a "big" breaking change, but it will likely affect folks who
do not have their PST version pinned since I just made a release. So, it
might be worth publishing this change in a follow-up.

Author: trallard

src/pydata_sphinx_theme/assets/styles/base/_base.scss

@@ -72,33 +72,36 @@ a {
   line-height: 1.15;
 }
 
+// From 0.16.1, the preferred variable for headings is --pst-color-heading
+// if you have --pst-heading-color, this variable will be used, otherwise the default
+// --pst-color-heading will be used.
 h1 {
   @extend %heading-style;
 
   margin-top: 0;
   font-size: var(--pst-font-size-h1);
-  color: var(--pst-color-heading);
+  color: var(--pst-heading-color, --pst-color-heading);
 }
 
 h2 {
   @extend %heading-style;
 
   font-size: var(--pst-font-size-h2);
-  color: var(--pst-color-heading);
+  color: var(--pst-heading-color, --pst-color-heading);
 }
 
 h3 {
   @extend %heading-style;
 
   font-size: var(--pst-font-size-h3);
-  color: var(--pst-color-heading);
+  color: var(--pst-heading-color, --pst-color-heading);
 }
 
 h4 {
   @extend %heading-style;
 
   font-size: var(--pst-font-size-h4);
-  color: var(--pst-color-heading);
+  color: var(--pst-heading-color, --pst-color-heading);
 }
 
 h5 {

src/pydata_sphinx_theme/assets/styles/variables/_color.scss

@@ -286,6 +286,9 @@ $pst-semantic-colors: (
 
   // assign the "duplicate" colors (ones that just reference other variables)
   & {
+    // From 0.16.1, the preferred variable for headings is --pst-color-heading
+    // if you have --pst-heading-color, this variable will be used, otherwise the default
+    // --pst-color-heading will be used
     --pst-color-heading: var(--pst-color-text-base);
     --pst-color-link: var(--pst-color-primary);
     --pst-color-link-hover: var(--pst-color-secondary);