add documentation for reloading font cache

[saranti]

PR summary

Closes #24872. Adds documentation that describes the process of making newly added fonts available to the fontmanager.

• Made public the load_fontmanager method which can be used in place of the deprecated matplotlib.font_manager._rebuild() method.
• Added a new Loading new fonts section to the fonts-in-matplotlib doc with an explanation of the methods of reloading the font cache, with example code.

PR checklist

• "closes #0000" is in the body of the PR description to link the related issue
• new and changed code is tested
• Plotting related features are demonstrated in an example
• New Features and API Changes are noted with a directive and release note
• Documentation complies with general and docstring guidelines

[tacaswell]

I don't think that this will actually work?

This will make a new font manager and return it to you, but it will not change the singleton that is used by the rest of the library or update the findfont and get_font_names held at the module level.

[saranti]

My testing procedure for this was:

• add a new font to mpl-data\fonts\ttf
• run a short plot with a text instance with family=new font
• see that the text doesn't update to the new font after multiple runs
• run the font_manager.load_fontmanager code
• run the plot again

Now the text is now set to the new font and a new entry in the font cache is present. The findfont and get_font_names methods both return the new font.
I did notice however, that the before and after fontmanager instances were the same object with the same ID.

[tacaswell]

... ok, I do not understand why that works 🤯

[tacaswell]

ok, question: are you running this all in the same process or each in its own Python process?

[saranti]

Each in their own separate process.

[tacaswell]

Unfortunately I do not think it is this simple because we keep a singleton of this cache and then re-expose its methods at the module level.

I think the steps here are:

• keep the load function private
• write top-level functions that replace find_font and get_font_names (minor API break but we need it to make sure if someone does from matplotlib.font_manager import find_font and then we update the cache the function they are holding onto is not the old one...I guess we could fake the method properties on a function but it is not worth it)
• write a new top level function like reload_fontcache or something similar name that updates the fontManager singleton. If someone has done from matplotlib.font_manager import fontManager I think we are stuck in a world where they will still have a reference to the old one! I guess we could deprecate it as a publicly accessible

An alternate path would be to update FontManager to be able to have its internal state updated.

[tacaswell]

An alternate to my last comment is to explain why this does work as it looks like it creates a new FontManger that we then throw away, but some how the existing FontManager is changed?

[anntzer]

Haven't read through the whole issue, but note that in the rebuild_if_missing branch at the end of findfont_cached, fontManager calls _load_fontmanager then replaces its __dict__ with the contents of the newly loaded instance (so the old one really becomes a copy of the new one).

See also #13810/#13852, which may be worth revisiting?

[tacaswell]

That is a bit heavy handed, but makes sense (a recache method might be better).

However the way this is hidden behind a cache, we will only automatically discover the new font if it is there when we search for it. It might be worth also adding a public way to clear that cache.