-
-
Notifications
You must be signed in to change notification settings - Fork 7.6k
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Explain that matplotlib must be built before the HTML documentation #1660
Conversation
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
It's actually more than that -- |
Should I add a second commit and mention that in doc/README.txt too? |
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, |
Perhaps a better error message from |
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.
Looks good. |
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