[Doc]: Documentation of rc parameters could be improved

[mwaskom]

Documentation Link

https://matplotlib.org/stable/tutorials/introductory/customizing.html#the-default-matplotlibrc-file

Problem

As far as I am aware of, the only documentation of "what can be changed through rc paramters" is a the literal-included default matplotlibrc file, which has comments for various options. This is a very cumbersome way to present information in 2022.

There's also no direct link for third-party packages that expose an interface for setting rc parameters and want to link to the source documentation. You could hardcode the url including the anchor, but (1) that will break the next time matplotlib reorganizes things, and (2) if you link directly to the "default matplotlibrc file", there's no context for what people are looking at and it's confusing why the information is being presented the way that it is.

Suggested improvement

Rendering this information as regular html with semantic markup would be a significant improvement. Specific short-term benefits would include:

• Visual differentiation of headers, parameters, defaults, and descriptions
• Site navigation to various sections (it can be hard to find what you're looking for: the file is 767 lines long, and the groups are not in alphabetical order)

Additionally, this would make it possible to explore more complex interfaces, like having a filtering functionality to show all parameters with a given substring ("color") in their name.

To address the second issue, I would suggest separating the specific parameter documentation from the more general "how you customize matplotlib" page, with it discussion of various methods for changing those parameters (style sheets, matplotlibrc file, etc.).

I appreciate that the default matplotlibrc file is currently the source of truth for this information and that it's not properly structured in a way that would facilitate extracting the information, so this wouldn't be trivial. But I think it would help a lot.

[timhoffm]

IMHO we should move to an argparse-like specification of the rcParams, e.g.

rc.add_parameter(
    'webagg.open_in_browser',
    type=bool,
    default=True,
    help="When True, open the web browser to the plot that is shown"
)

We can then use this specification to generate a template matplotlibrc, and nicely formatted documentation.

[story645]

This probably interacts w/ #6738 in some way given the idea behind that was to be able to write an rcparams to file.

I think a first pass/easy/low cost improvement to the rc-parameters is translating the file into a table and cross linking the parameters with any corresponding artist attribute they control.

[story645]

Um, I have a suggestion for maybe a good first issue version of sorting through the rc params, which is maybe take @mwaskom's suggestion of moving the documentation of the actual parameters to their own page, and then on that page maybe putting each each section of rc params as a table in a dropdown?