Building documentation and matplotlibrc

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

In practice, however, I have run into a few issues. First, the comment
regarding examples.directory indicates that this path must be
absolute. Is this really true?

The comment is wrong: a relative path will work (I just tried this).

Secondly, it seems that the doc/matplotlibrc file is completely
ignored.

I am not intimately familiar with the doc build system, but the way that
the "html" function in make.py copies matplotlibrc from mpl-data to
_static, I suspect that it is trying to ensure that that particular file
is used.

···

--
Jouni K. Sepp�nen

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

> In practice, however, I have run into a few issues. First, the comment
> regarding examples.directory indicates that this path must be
> absolute. Is this really true?

The comment is wrong: a relative path will work (I just tried this).

Awesome. Perhaps this should be corrected in the tree so it doesn't look
like I'm blatantly violating the documentation?

> Secondly, it seems that the doc/matplotlibrc file is completely
> ignored.

I am not intimately familiar with the doc build system, but the way that
the "html" function in make.py copies matplotlibrc from mpl-data to
_static, I suspect that it is trying to ensure that that particular file
is used.

Anyone else have further guidance?

- Ben

···

On Sun, 05 Dec 2010 23:03:02 +0200, Jouni K. Seppänen <jks@...278...> wrote:

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

> In practice, however, I have run into a few issues. First, the comment
> regarding examples.directory indicates that this path must be
> absolute. Is this really true?

The comment is wrong: a relative path will work (I just tried this).

Awesome. Perhaps this should be corrected in the tree so it doesn't look
like I'm blatantly violating the documentation?

> Secondly, it seems that the doc/matplotlibrc file is completely
> ignored.

I am not intimately familiar with the doc build system, but the way that
the "html" function in make.py copies matplotlibrc from mpl-data to
_static, I suspect that it is trying to ensure that that particular file
is used.

Anyone else have further guidance?

- Ben

···

On Sun, 05 Dec 2010 23:03:02 +0200, Jouni K. Seppänen <jks@...278...> wrote:

No, that is there so that the link from the customizing page

  http://matplotlib.sourceforge.net/users/customizing.html

to the "download matplotlibrc" link

  http://matplotlib.sourceforge.net/_static/matplotlibrc

works and gives an update matplotlibrc. It is not used in the doc
build to customize the settings of the docs. The files in _static are
just copied up to the web server but can be linked to from withing
rest.

JDH

···

On Sun, Dec 5, 2010 at 3:14 PM, Ben Gamari <bgamari.foss@...149...> wrote:

I am not intimately familiar with the doc build system, but the way that
the "html" function in make.py copies matplotlibrc from mpl-data to
_static, I suspect that it is trying to ensure that that particular file
is used.

Anyone else have further guidance?

Sorry to the Benjamin Drung, Scott Kitterman, and Sandro Tosi for not
including you in this thread earlier. I am trying to bring the
matplotlib 1.0.1 packaging into compliance with the debian packaging
requirements.

Unfortunately, matplotlib now includes out-of-tree sample data which is
downloaded during the documentation build process. To avoid this we need
to override a setting in matplotlibrc during the documentation build and
package these data in a separate source tarball. Most of this work has
been done (see my PPA[1]) but unfortunately the configuration changes
are non-trivial.

>> I am not intimately familiar with the doc build system, but the way that
>> the "html" function in make.py copies matplotlibrc from mpl-data to
>> _static, I suspect that it is trying to ensure that that particular file
>> is used.
>>
> Anyone else have further guidance?

No, that is there so that the link from the customizing page

  http://matplotlib.sourceforge.net/users/customizing.html

to the "download matplotlibrc" link

  http://matplotlib.sourceforge.net/_static/matplotlibrc

works and gives an update matplotlibrc. It is not used in the doc
build to customize the settings of the docs. The files in _static are
just copied up to the web server but can be linked to from withing
rest.

I'm glad to hear that this file isn't used. This should make packaging
much easier.

That being said, I've tracked down the reason for the configuration in
doc/matplotlibrc not being used. It seems that sphinx runs the examples
in their current directory (I suppose this is to be expected).

It seems that there is a (as far as I can tell undocumented, please fix
this) MATPLOTLIBRC environment variable which can be used to override
the location of the matplotlibrc used. This could be useful in
specifying the matplotlibrc used during the documentation build process
but unfortunately this would require an absolute path which, again,
complicates the packaging (i.e. I don't know the best way to accomplish
this). Suggestions?

Thanks,

- Ben

[1] OpenID transaction in progress

···

On Sun, 5 Dec 2010 17:16:44 -0600, John Hunter <jdh2358@...149...> wrote:

On Sun, Dec 5, 2010 at 3:14 PM, Ben Gamari <bgamari.foss@...149...> wrote: