search

matplotlib / basemap

Plot on map projections (with coastlines and political boundaries) using matplotlib
MIT License
776 stars 392 forks source link

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

Closed TomLav closed 9 months ago

TomLav commented 1 year ago

Documentation Link

No response

Problem

Basemap is deprecated and all users should be using Cartopy.

In 2020, https://github.com/matplotlib/matplotlib/pull/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 commented 1 year ago

Should this be better handled on the basemap issue tracker?

molinav commented 1 year ago

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:

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

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 commented 1 year ago

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 commented 1 year ago

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 commented 1 year ago

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 commented 1 year ago

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 commented 9 months ago

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 commented 9 months ago

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 commented 9 months ago

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 commented 9 months ago

@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 commented 9 months ago

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 commented 9 months ago

@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 commented 9 months ago

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 commented 9 months ago

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

tacaswell commented 9 months ago

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

molinav commented 9 months ago

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

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.