search

sympy / sympy

A computer algebra system written in pure Python
https://sympy.org/
Other
12.61k stars 4.34k forks source link

Access `objects.inv` of old sympy versions for intersphinx #26688

Open hugokerstens opened 1 month ago

hugokerstens commented 1 month ago

The /latest docs have already been updated to 1.13.0rc1, but the latest installable sympy version is still 1.12.1. This breaks intersphinx if using classes that have been moved in 1.13.

For example, our CI uses the latest version of sympy: 1.12.1. It loads objects.inv from https://docs.sympy.org/latest/objects.inv, which is version 1.13.0rc1. This breaks our docs build, as sympy.MatrixBase has moved in 1.13:

WARNING: py:class reference target not found: sympy.matrices.matrices.MatrixBase

Two questions:

  1. Shouldn't the /latest docs always point to the latest installable version?
  2. Should there be a standardized way to access old objects.inv of all sympy versions?

Thanks!

moorepants commented 1 month ago

Since we stopped showing all old versions of sympy documentation on the docs website, it has become impossible to use intersphinx links without hyperlinks breaking. So this specific issue is also related to us simply not carefully providing versioned docs. These links break for me in downstream projects and being able to link to specific versions would solve that.

asmeurer commented 1 month ago

We really shouldn't be updating the latest docs on release candidates. It should be possible to revert this change in the docs repo.

asmeurer commented 1 month ago

It looks like this change was made automatically by GitHub Actions. I went ahead and reverted it. CC @oscarbenjamin

oscarbenjamin commented 1 month ago

I think that we should upload docs for prereleases and keep the docs for old releases as well.

WARNING: py:class reference target not found: sympy.matrices.matrices.MatrixBase

Ideally it should be possible to reference this like sympy.MatrixBase rather than the fully qualified module.

oscarbenjamin commented 1 month ago

I think that we should upload docs for prereleases and keep the docs for old releases as well.

WARNING: py:class reference target not found: sympy.matrices.matrices.MatrixBase

Ideally it should be possible to reference this like sympy.MatrixBase rather than the fully qualified module.

oscarbenjamin commented 1 month ago

I think that we should upload docs for prereleases and keep the docs for old releases as well.

WARNING: py:class reference target not found: sympy.matrices.matrices.MatrixBase

Ideally it should be possible to reference this like sympy.MatrixBase rather than the fully qualified module.

oscarbenjamin commented 1 month ago

I think that we should upload docs for prereleases and keep the docs for old releases as well.

WARNING: py:class reference target not found: sympy.matrices.matrices.MatrixBase

Ideally it should be possible to reference this like sympy.MatrixBase rather than the fully qualified module.

asmeurer commented 1 month ago

I think that we should upload docs for prereleases and keep the docs for old releases as well.

The problem is that Google would consistently return results for ancient versions. People copy-paste a versioned URL and Google learns that in its index.

Ideally it should be possible to reference this like sympy.MatrixBase rather than the fully qualified module.

I completely agree. I looked into this in the past but it wasn't easy to get Sphinx to do this. I'd need to take a look again but it might require making some reorganization in the code. But worst case scenario we might have to rewrite autodoc, which I don't particularly want to do. This is also tied to the issue for putting function docs in their own page. Ideally the docs would never reference module names except for functions that aren't in the main namespace.

moorepants commented 1 month ago

The problem is that Google would consistently return results for ancient versions. People copy-paste a versioned URL and Google learns that in its index.

I remember that was the reason the old versions were removed but many other projects have the old versions present and, I suspect, just deal with this issue. Just last night I saw NumPy 1.10 and 1.26 appear in a search for NumPy fft.

Ideally it should be possible to reference this like sympy.MatrixBase rather than the fully qualified module.

I tried a length to do this also in my book but never succeeded. I could only get the full path to work.

hugokerstens commented 4 weeks ago

The problem is that Google would consistently return results for ancient versions. People copy-paste a versioned URL and Google learns that in its index.

I guess part of the solution is to minimize visits to docs with a versioned URL. If you always provide the latest version under latest, and don't do redirects I would assume the problem will be minimal. Especially if you combine it with setting a priority in the sitemap. For example celery does it this way, see https://docs.celeryq.dev/sitemap.xml.

hugokerstens commented 4 weeks ago

@asmeurer Release candidate 2 triggered a build to the latest docs again, could you be so kind to revert this again? Thanks!

oscarbenjamin commented 4 weeks ago

There is supposed to be a guard for this: https://github.com/sympy/sympy/blob/015e6a5b553339651558920e58c3e0010c3694aa/.github/workflows/release.yml#L19-L22 https://github.com/sympy/sympy/blob/015e6a5b553339651558920e58c3e0010c3694aa/.github/workflows/release.yml#L176-L180 I'm not sure why that doesn't do what it is intended to do.