How can we improve on that?

This definitely looks better than what's currently there. I think subheadings based on the artist/object that the rcParam applies to - like #lines, which will also make the right hand side really nice for quick skims I think. I think the two ways to achieve that are probably either manually add a family or peel off the family with a .split?

Alternative: It would likely be feasible to define the rcParams via a TOML file, which we would carry around and read at startup like we do with matplotlibrc.

Compare:

Param("timezone", "UTC", validate_string,
    description="a pytz timezone string, e.g., US/Central or Europe/Paris"),
Param("pcolor.shading", "auto", ["auto", "flat", "nearest", "gouraud"]),
Param("figure.constrained_layout.hspace", 0.02, validate_float,
    description="Spacing between subplots, relative to the subplot sizes.  Much "
                "smaller than for tight_layout (figure.subplot.hspace, "
                "figure.subplot.wspace) as constrained_layout already takes "
                "surrounding texts (titles, labels, # ticklabels) into account."),

and:

[timezone]
default = "UTC"
validator = "validate_string"
description ="a pytz timezone string, e.g., US/Central or Europe/Paris"

[pcolor.shading]
default = "auto"
validator = '["auto", "flat", "nearest", "gouraud"]'

[figure.constrained_layout.hspace]
default = 0.02
validator = "validate_float"
description = """
Spacing between subplots, relative to the subplot sizes.  Much
smaller than for tight_layout (figure.subplot.hspace, "
figure.subplot.wspace) as constrained_layout already takes
surrounding texts (titles, labels, # ticklabels) into account.
"""

Which one is easier to maintain?

There'll be slight complications that we need to be able to express None as a default value and that we have to define validators as strings and map them to code objects at runtime, but nothing that cannot be done.

Which one is easier to maintain?

The toml file looks way easier to read/find the right value. And I like that the leveling structure means we can do group level stuff trivially (if I'm reading the TOML docs correctly), eg:

[figure.constrained_layout]
description = "default settings for constrained layout, see <link to constrained layout docs>" 

I think it has been suggested for years that the matplotlibrc be a Python file instead of some parsable text format?

@jklymak Tim is proposing a replacement for how rcParams are specified in rcsetup.py. Roughly this replaces the _validators dictionary and the adds in the default values and description from the default rcParams file so that all the info about the param is in one place.
ETA: basically, we should be able to generate a default matplotlibrc file from the specs rather than the current scheme where defaults are defined in the matplotlibrc file.

Separately it might be nice for users to be able to specify params using a TOML structure, but generally they're only going to need to specify the values so the structure here is a bit overkill for that.

Sure I understand that - however, I don't see why we would add a new TOML format to the mix.

Chiming in here with a note about a tool I used once in a work project for schema validation: https://docs.python-cerberus.org/

Thanks for the hint. Though I think schema validation is not our primary concern for now. We have potentially two schemas:

• the config_parameter_schema, but if we define (or parse) that into a dataclass, errors will show up. Also the input is on our side and rarely changes.
• user-defind rcParams setttings. These are just key-value pairs, with a potentially complicated (in the sense of allowed values, not in the sense of structure) value type. A schema is not much help here either.

however, I don't see why we would add a new TOML format to the mix.

Because it's a ready made solution to the problem of defining specs for nested configurations, which is more or less what rcParams are. The alternative proposal of wrapping everything in Param objects (or the like) would likely grow to something that looks like TOML in object form if we want to make the groupings explicit, which I think we do because that's really useful for documentation purposes.

Sure I understand that - however, I don't see why we would add a new TOML format to the mix.

It's a variant how to systematically represent that information. We are completely free to decide which one we like better.

What I like about the TOML approach:

• The parameter name stands out [param.name], it's visually separated from the other values

• There's no extra syntactic clutter that we need in Python: no class name, no parentheses, no commas

• Multiline strings look a bit nicer. This is mainly because your keys are not indented.

  [some.param]
  description="""
  A longer description that spans multiple
  lines.
  """

  In Python you do one of

  implicit concatenation of single lines (needs extra quotes on each line and ensure that there's a space at the end of each line.

      Param(
          description="A longer description that spans multiple "
                      "lines."
      )

  or (visually breaking the indentation)

      Param(
          description="""\
   A longer description that spans multiple
  lines.
  """
      )

  or (adding additional space into the string)

      Param(
          description="""\
              A longer description that spans multiple
              lines.
              """
      )

  Also, depending on the variant, effective line length gets much shorter, which means we need more wrapping.

What I don't like about the TOML approach:

• Overhead for carrying a file around (but we right now do this with matplotlibrc) so not too bad.
• No native value for None
• We must define a pattern how we define validators (e.g. as string) and then parse them into the actual objects on load.

Overhead for carrying a file around (but we right now do this with matplotlibrc) so not too bad.

I think it'd be nice to pull the configuration out of rcsetup even if we don't go the TOML route.

Overhead for carrying a file around (but we right now do this with matplotlibrc) so not too bad.

I think it'd be nice to pull the configuration out of rcsetup even if we don't go the TOML route.

I did not do this for a start, because one then needs to import all the validators, and that gets messy. But rearrangement is possible and will happen in some form.