search

readthedocs / readthedocs.org

The source code that powers readthedocs.org
https://readthedocs.org/
MIT License
8.03k stars 3.58k forks source link

Embed API: fully deprecate/remove embed API V2 #10677

Open stsewd opened 1 year ago

stsewd commented 1 year ago

What's the problem this feature will solve?

We are still generating fjson files for sphinx builds (https://github.com/readthedocs/readthedocs-sphinx-ext/pull/126), at first I thought they were used by our search only, but they are actually being used by th embed API V2 as well. If we fully deprecate/remove the embed API V2, we can delete all the code related to fjson files (generating then and storing them in storage).

https://github.com/readthedocs/readthedocs.org/blob/40bfe63fd9db2bfa86f83c412cbb3baca104373a/readthedocs/embed/views.py#L192-L202

Describe the solution you'd like

Fully deprecate that endpoint, similar to the recent deprecations we have been doing, maybe contact the projects that are using it.

Alternative solutions

Additional context

humitos commented 1 year ago

I took a look at NR and I found we have just a few projects hitting this endpoint in the last 90 days: https://onenr.io/0PwJEXYO7Q7. We have 28 projects hitting this API and it's mainly because they are using an older version of sphinx-hoverxref

The change from Embed v2 to v3 was done in https://github.com/readthedocs/sphinx-hoverxref/pull/146 and it was released on 0.8b1 and we are on 1.3.0 now.

The good news here is should be easy for these projects to just update this dependency to solve the issue.

I agree with the plan here: deprecate, contact users, wait a month or so, and remove the endpoint.

ericholscher commented 6 months ago

One idea here: stop generating fjson for new versions, but keep it around so old hoverxref keeps working for some time.

ericholscher commented 3 months ago

Once we migrate all users away from using our Sphinx extension, fjson files won't be generated for anyone. People will need to upgrade their version of the hoverxref Sphinx extension to fix this.

Old versions of docs will break hoverxref, but that's probably fine for old versions. New versions can use the new sphinx extension and they will work?