Explain that matplotlib must be built before the HTML documentation

[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

[mdboom]

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]

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]

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]

@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]

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

Thanks @vterron.

[mdboom]

Looks good.