It is getting increasingly difficult to build the matplotlib documentation

[NelleV]

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 (!!!!)

[matthew-brett]

Recently, I've taken to adding doc-requirements.txt file to the top level of my projects, and a doc/README file with instructions to run pip install -r ../doc-requirements.txt.

[afvincent]

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.yml or 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]

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]

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]

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]

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]

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]

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:

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

—
You are receiving this because you are subscribed to this thread.
Reply to this email directly, view it on GitHub
#7040 (comment),
or mute the thread
https://github.com/notifications/unsubscribe-auth/AARy-E9bT6bXYsxRVnjN_D2Ef74j0kajks5qnT3ngaJpZM4J1MxK
.

[jenshnielsen]

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]

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]

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]

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

Whoops - sorry Nelle - didn't see this until now. Will email a requirements file.

[NelleV]

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.