Embed API: fully deprecate/remove embed API V2

[stsewd]

What's the problem this feature will solve?

We are still generating fjson files for sphinx builds (readthedocs/readthedocs-sphinx-ext#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).

readthedocs.org/readthedocs/embed/views.py

Lines 192 to 202 in 40bfe63

	def _get_doc_content(project, version, doc):
	storage_path = project.get_storage_path(
	'json',
	version_slug=version.slug,
	include_file=False,
	version_type=version.type,
	)
	file_path = build_media_storage.join(
	storage_path,
	f'{doc}.fjson'.lstrip('/'),
	)

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

• Just stop generating fjson files for new builds. This can be unexpected for users.
• Try to re-use some code from V3 to parse the html files instead, this may require some work for something that we will eventually remove.

Additional context

• Search: remove non-generic parser code #10676

[humitos]

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 readthedocs/sphinx-hoverxref#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]

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

[ericholscher]

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?

[humitos]

Now that everybody is on addons, I think we are ready to perform this removal. I'm adding this issue to the next sprint and assigning it Santos. I think it shouldn't be a ton of work.

[ericholscher]

I think the main work is reaching out to old users and getting them to upgrade the sphinx extension. There are only a few major users from what I remember.

This dashboard is a good place to start: https://onenr.io/0EjOLWaJGQ6

[stsewd]

I checked CF, and we have traffic only on api/v2/embed/, v1 and proxied API don't have any traffic.

I think most of the traffic is from the old sphinx-hoverxref extension, users can just upgrade to use the new API.

What are we thinking for the deprecation? Blog post + brown out dates?

[humitos]

What are we thinking for the deprecation? Blog post + brown out dates?

That would be great!

[humitos]

This work is done already. Closing the issue.