[Doc]: (More) Clearly mark Basemap as deprecated

[TomLav]

Documentation Link

No response

Problem

Basemap is deprecated and all users should be using Cartopy.

In 2020, matplotlib/matplotlib#16495 removed references to Basemap from matplotlib's documentation. Is it now time to more clearly mark Basemap as deprecated on https://matplotlib.org/basemap/ ?

I do see that the deprecation is described at the bottom of https://matplotlib.org/basemap/ but:

1. this statement can be missed (I recently met a user that had missed the information);
2. the statement is only on the main Basemap doc page, not in pages linked from there (random example https://matplotlib.org/basemap/users/mapsetup.html).

Suggested improvement

Place bold/red warning statements on all pages of the Basemap documentation, starting from https://matplotlib.org/basemap/

[tacaswell]

Should this be better handled on the basemap issue tracker?

[molinav]

Hi @TomLav! The basemap package was deprecated from 2016 until February 2022, but it is not deprecated as of today. It is being slowly (but actively) developed and maintained again since December 2021.

During this time, the basemap 1.3.x series has been developed as a transition period to put basemap in a fit state again. One of the major problems that basemap was facing was related to its packaging (e.g. the need of building GEOS by oneself). You can see that this is now solved and that precompiled wheels (for Windows and GNU/Linux) are available in PyPI:

• https://pypi.org/project/basemap
• https://pypi.org/project/basemap-data
• https://pypi.org/project/basemap-data-hires

Furthermore, thanks to other colleagues in the community (e.g. @ReimarBauer), effort was added to provide conda packages in conda-forge too:

• https://anaconda.org/conda-forge/basemap
• https://anaconda.org/conda-forge/basemap-data
• https://anaconda.org/conda-forge/basemap-data-hires

The latest bugfix release (1.3.6) dates from 31 October 2022 (just one month ago).

You are totally right about the fact that the docs are at the moment misleading. The docs at https://matplotlib.org/basemap have not been updated although the library has been in development again. This has been the result of a triage decision: my time is limited, I take care of basemap in my free time. But I am aware that the docs are severely outdated, and I want to target it for basemap 1.4.0. At the time I took over the maintenance of basemap, I thought that having a well packaged basemap was more important.

[TomLav]

Hello @molinav, thank you for your answer and for the time you and your colleagues devote to maintaining and developing free and open source software.

To be clear, I wrote "Basemap is deprecated" because this is the latest information I had, and what is on Basemap's current online documentation:

Basemap is deprecated in favor of the Cartopy project. See notes in Cartopy, New Management, and EoL Announcement for more details.

Does matplotlib need both Basemap and Cartopy is not a discussion I'll open here, but it would no doubt be an interesting one.

For the time being, IMHO, you should indeed update the documentation soon and clearly state the maintenance status of Basemap. As far as I am concerned, this issue can be closed.

[molinav]

I think you are totally right, @TomLav. Since the basemap packaging is found in an "acceptable" state (compared to one year ago), your opened issue is a clear hint for me that the docs should become a first priority now. Please leave the issue open, it will help me organise the next items to address.

[ruthpozuelo]

It would be great if the deprecation notice is updated. Even though I knew (thnaks to @TomLav ) that basemap is "alive", i had to come to double check i didnt dream about it.

[ReimarBauer]

May be we should try to get into this program. I don't know if there are umbrellas we can join, similiar to gsoc psf umbrella.

https://developers.google.com/season-of-docs/docs/timeline
https://developers.google.com/season-of-docs

[molinav]

I have been trying to update the basemap docs several times without success.

In my last attempt, I tried with the classic approach using the gh-pages branch. The GitHub deployment workflow shows success, but the website never gets updated. I have not added any new content, but I have moved the old docs into the ./1.2.1 folder and created a ./stable symlink pointing to ./1.2.1, in preparation before adding the ./1.4.0 docs. Neither ./1.2.1 nor ./stable are reachable after the deployment, that is why I think that the deployment had no effect.

The "Pages" section in "Settings" looks ok to me. We would need some help from a matplotlib member with more knowledge.

[tacaswell]

attn @QuLogic

We now host all of the docs off of a digital ocean droplet configured at https://github.com/matplotlib/matplotlib.org/blob/main/matplotlib.org.yml

[tacaswell]

The issue is we did not install the webhooks to notify the system when new docs are pushed: https://github.com/matplotlib/basemap/settings/hooks

[molinav]

@tacaswell Thanks for finding the issue! Would it be possible to bring the webhook also to this repository? I do not have access to any other matplotlib repository, so I do not know how the webhook should look like.

[tacaswell]

Sorry, yes there is the need for some secret management that needs to be done, @QuLogic or I will take care of this (hopefully this week).

In the mean time I went in and did the webhooks job "by hand" so what ever the current gh-pages is is what is being served.

[molinav]

@tacaswell No worries! I have just checked it, and I can confirm that the (slight) changes are present: so the "latest" old docs are now placed under https://matplotlib.org/basemap/1.2.1, and https://matplotlib.org/basemap simply redirects to them. At some point (soon), I will add the corresponding docs for basemap 1.4.0 and will make https://matplotlib.org/basemap point to the new docs.

It is perfectly fine to get the webhook this week or a bit later. The docs have been outdated for very long, so waiting a few more days is not that a big issue. I am quite happy that you found the source of the issue, because I was already out of ideas. Thanks!

[QuLogic]

The server is already all set up for it; for whatever reason the webhook was not configured here. It just needed to be added and now updates should flow through (from the gh-pages branch).

[QuLogic]

PS, you may also want to remove some of the old dead webhooks.

[tacaswell]

I took out the two dead webhooks (tenxer.com and travisCI).

[molinav]

Thanks @tacaswell and @QuLogic for your help with the docs. I have just updated the latest docs successfully, with the following changes:

• The deprecation notice is removed.
• All the broken links are replaced with the appropriate new links, using HTTPS whenever possible.
• All the docs examples are fixed, including broken references to DAP servers or outdated Python syntax.
• The installation process is described properly, for both pip and conda, as well as how to build from source (this should be limited to very specific cases, e.g. Cygwin, since Windows, GNU/Linux and MacOS are well covered now with precompiled wheels or with conda packages).

I am aware that the development goes slowly, but after two years of basemap maintenance, I am still quite happy with the current status of the library if we look back to 2020. Several functionality bugs addressed by users have been fixed, some of them with PR from the same users that found them. The packages are uploaded regularly to PyPI and conda-forge, precompiled for the most common target users, which has reduced the number of people struggling with the build process. Removing this deprecation notice feels to me as a small recognition to the maintenance of these last two years.

With your permission, I will be closing this issue, because the docs are now up to date, which was the original source of the problem.