Building documentation and matplotlibrc

Ben Gamari <bgamari@...149...> writes:

It seems that matplotlib's sphinx extension calls
matplotlib.rcdefaults() after rendering each figure, thus resetting
examples.download to True (as set in rcsetup.py).

Right, and it sets figure.figsize after it. I guess you will want to set
examples.download in the same function.

The documentation claims that this function will "Restore the default rc
params - the ones that were created at matplotlib load time."

rcdefaults()'s implementation appears to implement the latter, updating
rcParams from rcParamsDefault in rcsetup.py, which appears to describe
the factory default values. Perhaps we should
rcParamsDefault.update(rcParams) after loading matplotlibrc?

I think you're better off modifying the sphinx extension. rcdefaults has
a useful purpose, and the extension is trying to use it for that
purpose: to avoid having the user's configuration mess up the
documentation. If you were to update rcParamsDefault with the
matplotlibrc parameters, you might accidentally change the example
output.

···

--
Jouni K. Sepp�nen
http://www.iki.fi/jks

Ben Gamari <bgamari@...149...> writes:

> It seems that matplotlib's sphinx extension calls
> matplotlib.rcdefaults() after rendering each figure, thus resetting
> examples.download to True (as set in rcsetup.py).

Right, and it sets figure.figsize after it. I guess you will want to set
examples.download in the same function.

NAK.

This seems like an _awful_ hack. If the user specifies in matplotlibrc
that they don't want to download sample data (or any preference for that
matter), then they _really_ don't want to download sample data and we
should take their word for this.

It's one-time hacks like this that make matplotlib the nightmare to
package that it is. Wholesale overriding of the user's preferences seems
like a big no-no, even when it comes to generating documentation. If a
particular example _absolutely needs_ to override a specific rc option
then it should modify that option and only that option. After this, the
configuration should be returned to the user's default.

> The documentation claims that this function will "Restore the default rc
> params - the ones that were created at matplotlib load time."

> rcdefaults()'s implementation appears to implement the latter, updating
> rcParams from rcParamsDefault in rcsetup.py, which appears to describe
> the factory default values. Perhaps we should
> rcParamsDefault.update(rcParams) after loading matplotlibrc?

I think you're better off modifying the sphinx extension. rcdefaults has
a useful purpose, and the extension is trying to use it for that
purpose: to avoid having the user's configuration mess up the
documentation. If you were to update rcParamsDefault with the
matplotlibrc parameters, you might accidentally change the example
output.

I'm not sure I understand what this purpose might be. If the user sets a
preference, then they want that preference to be reflected in _all_
matplotlib output, including the examples. By overriding matplotlibrc,
we are doing nothing but setting ourselves up to thoroughly confuse the
user (not to mention lowly packagers like me). If the user takes a block
of code from an example then he expects that the output in ipython will
be identical to that generated in the documentation. If it is not, he's
forced to embark on a wild goose chase through the code looking for the
line where some developer thought their example was too good for my
carefully chosen preferences (or simply give up in frustration).

- Ben

···

On Thu, 09 Dec 2010 23:55:05 +0200, Jouni K. Seppänen <jks@...278...> wrote: