Repository navigation
It is getting increasingly difficult to build the matplotlib documentation #7040
Description
I've had to build the matplotlib documentation several times in the past couple of months, and everytime, it is getting increasingly difficult to build the documentation.
The number of packages required has drastically increased in the past year or so, including packages where the installation instruction is pretty much missing (http://matplotlib.org/basemap/users/installing.html)
Having had to set up a new computer recently, I am running in many problems that I believe many core devs are not aware.
This unfortunately increases the level required for new contributors to do documentation changes. I would consider removing a bunch of dependencies…
Note that the doc/README.txt only mentions that sphinx is required, and the documentation then crashes after 5 minutes of build.
Here is an uncomplete list of packages required to build the documentation: numpydoc, basemap, colorspacious, mock, ipython (!!!!)
Activity
matthew-brett commentedon Sep 5, 2016
Recently, I've taken to adding
doc-requirements.txtfile to the top level of my projects, and adoc/READMEfile with instructions to runpip install -r ../doc-requirements.txt.afvincent commentedon Sep 5, 2016
If it may help, there was a brief discussion on the Gitter chat room a while ago (August, 6) because I was also struggling to build the doc. As a workaround, @Kojoley and @has2k1 suggested to have a look at the files used by Travis, like
.travis.ymlor simply the Travis logs.The idea of making a dedicated PR was also in the air, but unfortunately I have very limited bandwidth since a month.
tacaswell commentedon Sep 5, 2016
Some of the dependencies became hard dependencies (ex basemap) after the docs deployed to the website (by me) were missing figures due to lack of previously optional dependencies.
has2k1 commentedon Sep 5, 2016
Maybe related, to reduce the unfamiliarity the documentation system it may be worthwhile to switch to more recent sphinx build files. This would be a big undertaking and should be a separate issue.
tacaswell commentedon Sep 5, 2016
Spoke about this with @efiring and @jenshnielsen
@matthew-brett has the right idea. All of these deps should go in a requirements.txt in the build directory, travis should install it's extra deps from there, and the existence of this file needs to go into the documentation someplace.
NelleV commentedon Sep 6, 2016
As far as I know, basemap can't be installed through pip which is the major problem IMO. If the rest of the dependencies are documented, it'd be fine.
I'm also having a problem currently with conda, and a hand built matplotlib (it segfaults), which makes installing basemap through conda impossible as well.
jenshnielsen commentedon Sep 6, 2016
I think we should consider dropping the basemap example to loose that dependency at least until basemap is rereleased on pypi. Basemap has it's own documentation and we are linking to it from the third party library section of the docs anyway
WeatherGod commentedon Sep 6, 2016
As the maintainer of basemap, I would agree to drop basemap as a dependency
-- regardless of when it is released to pypi. Just link to its
documentation instead. We should be encouraging Cartopy, anyway.
On Tue, Sep 6, 2016 at 6:18 AM, Jens Hedegaard Nielsen <
notifications@github.com> wrote:
jenshnielsen commentedon Sep 6, 2016
Specially that would drop this section http://matplotlib.org/devdocs/users/screenshots.html#basemap-demo from the docs unless we replace it with a static image
NelleV commentedon Sep 6, 2016
I would be in favor of adding a static image and linking to the project webpage for more examples on basemap.
Maybe this particular example could be moved to basemap documentation as well?
jenshnielsen commentedon Sep 6, 2016
Yes if that example is not in basemap's docs it should probably be. We also have a reference to basemap in http://matplotlib.org/devdocs/thirdpartypackages/index.html#mapping-toolkits which is a more natural place IMHO
NelleV commentedon Sep 6, 2016
@matthew-brett I am lazy: can you send me the pip requirement file? I've documentated the list of dependencies, but never use pip requirement file.
matthew-brett commentedon Sep 6, 2016
Whoops - sorry Nelle - didn't see this until now. Will email a requirements file.
NelleV commentedon Sep 6, 2016
I've created a PR with the different element of this PR. I personally am in favor of removing some dependencies or shipping them with matplotlib (numpydoc and colorspacious/the used method of colorspacious could be shipped very easily with matplotlib, and I am pretty sure mock could be removed). Right now, I have just implemented basic import tests in the sphinx conf file to ensure dependencies are installed.