[DOCUMENTATION] Glyph Line, Text, and Fill defaults in theme yaml are undocumented

The reference manual page for themes does not document the ability to set default line, text, and fill attributes for glyphs in the theme.yaml file. For example this is valid:

attrs:
  Axis: {}
  Grid: {}
  Plot: {}
  Title:
    text_color: '#f4a4c0'
  Toolbar: {}
fill_defaults:
  fill_color: '#e32400'
line_defaults:
  line_color: '#2b1276'
text_defaults:
  text_color: '#7a4900'
  text_font: Calibri

and has the effect, for example, of setting the default font in all Text Glyphs to “Calibri” unless specifically overridden by, for example, providing defaults for the Text Glyph. The relevant code is in theme.py where the constructor for the Theme class includes:

    self._line_defaults = self._json.get('line_defaults', _empty_dict)
    self._fill_defaults = self._json.get('fill_defaults', _empty_dict)
    self._text_defaults = self._json.get('text_defaults', _empty_dict)

and there is the method:

def _add_glyph_defaults(self, cls, props):
        from ..models.glyphs import Glyph
        if issubclass(cls, Glyph):
            if hasattr(cls, "line_alpha"):
                props.update(self._line_defaults)
            if hasattr(cls, "fill_alpha"):
                props.update(self._fill_defaults)
            if hasattr(cls, "text_alpha"):
                props.update(self._text_defaults)

The documentation also includes the somewhat cryptic annotation:

    The plotting API's defaults override some theme properties. Namely:
    `fill_alpha`, `fill_color`, `line_alpha`, `line_color`, `text_alpha` and
    `text_color`. Those properties should therefore be set explicitly when
    using the plotting API.

which merits more explanation.

[jeremy9959]

My thought was yes, to use abstract classes and yes, that is what it would look like to the user. I will do some experimentation to see what this is like in practice. Incidentally I also understand what is going on with #6821. I can make a PR to clear that up but before I do I could use some guidance as to what seems most reasonable, it’s described there.

[bryevdv]

If you mean create purely abstract FilledGlyph etc, that seems reasonable though we should add tests to make sure e.g. that all FilledGlyph subclasses do in fact add fill properties. (And add the same kind of tests for XYGlyph too)

If you mean actually adding the properties on FilledGlyph that’s not impossible, but would require additional work to the documentation automation to make sure that the help strings for the inherited properties can still be customized on a per-class basis. (And I am not sure how hard that would be offhand.)

Do you then imagine this is what things would look like for users?

attrs:
    FilledGlyph:
        fill_alpha: 0.5