Explain that matplotlib must be built before the HTML documentation #1660

Merged
merged 4 commits into from Jan 23, 2013

4 participants

@vterron

Attempting to generate the HTML documentation right after cloning the
repository results in a cryptic error message as one of the required
files, mpl-data/matplotlibrc, is created when matplotlib is built. It
seems that other people have come across this problem in the past [1],
so mentioning it here might be of help to newcomers.

[1] http://sourceforge.net/mailarchive/message.php?msg_id=21478615

@vterron vterron Explain that matplotlib must be built before the HTML documentation
Attempting to generate the HTML documentation right after cloning the
repository results in a cryptic error message as one of the required
files, mpl-data/matplotlibrc, is created when matplotlib is built. It
seems that other people have come across this problem in the past [1],
so mentioning it here might be of help to newcomers.

[1] http://sourceforge.net/mailarchive/message.php?msg_id=21478615
e532e18
@mdboom
Matplotlib Developers member

It's actually more than that -- matplotlib must be installed (so that the docstrings are accessible) before the documentation can be built.

@vterron

Should I add a second commit and mention that in doc/README.txt too?

@NelleV

This is something general to python projects and sphinx, not something specific to matplotlib. Sphinx uses the installed version of the documentation to built the documentation of this project. I don't think it is worth explaining the matplotlibrc creation in the README. I'd just mention that the package needs to be installed before building the documentation.

@pelson
Matplotlib Developers member

This is something general to python projects and sphinx, not something specific to matplotlib. Sphinx uses the installed version of the documentation to built the documentation of this project. I don't think it is worth explaining the matplotlibrc creation in the README. I'd just mention that the package needs to be installed before building the documentation.

@NelleV - your absolutely right - most python packages depend on the package they are documenting being installed before you can build the docs with sphinx. It is worth noting however, that the biggest python project of all, namely python-core, doesn't have this requirement (and instead has a lot of duplication of documentation and a lot of objects which do not have docstrings at all!).

If @vterron (or anybody else) has tripped over this, and we have it in our power to make it easier for everybody to be able to get involved with improving the docs, then I think we should.

@vterron - yes, lets get the message in a state where we are happy for it to get merged, and if, at that point, we have a big commit list, we can always squash it down to a single commit.

Cheers,

@mdboom
Matplotlib Developers member

Perhaps a better error message from make.py when we don't have a matplotlib installation or a matplotlibrc file would be even better -- we can document all we like, but often a clear message why something is going wrong is even better.

vterron added some commits Jan 20, 2013
@vterron vterron Show custom error message if we don't have a matplotlibrc file
Even if the README.txt file explicitly mentions that matplotlib must
have been built before the documentation can be generated, a better
error message will be of help to those developers who happen not to
read it.
b236b0f
@vterron vterron Show custom error message if we don't have a matplotlib installation d8221ab
@vterron vterron Mention that matplotlib must be installed before building the docs 3a38438
@vterron

@pelson - the README now explains that matplotlib must have been built and installed before the docs can be generated. As @mdboom suggested, more specific error messages are shown to the user if that is not the case.

@pelson
Matplotlib Developers member

This looks good to me. 👍
@mdboom - please comment & merge when happy.

Thanks @vterron.

@mdboom
Matplotlib Developers member

Looks good.

@mdboom mdboom merged commit ffdd946 into matplotlib:master Jan 23, 2013

1 check was pending

Details default The Travis build is in progress
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment