Adddons: allow injecting an "always live" JavaScript file

[humitos]

We talked about giving users a way to inject a JavaScript file they control using our Cloudflare Worker infrastructure to allow them manipulate frozen documentations.

This could be used in different ways to fix bugs or add features to a particular frozen set of docs or even to all the versions. The user can make usage of API data to filter by version or not
(e.g. if (versions.current == "v3.0") { .. do something ...} )

The script could live in Read the Docs itself using a relative URL, or outside it, using an absolute URL.

Example using Sphinx

1. Tell Sphinx to include static folder
2. Include a readthedocs.js file in your project
3. Make AddonsConfig.userjsfile_src to be /en/full-feature/readthedocs.js from addons admin UX

The console will render the following:

Related #11474
Related readthedocs/addons#431

[humitos]

I changed this approach to simplify it a little. Instead of using an HTTP header file, I implemented this as an addon. We are returning addons.userjsfile in the API response and is the addon responsibility to inject this file into the document.

I did the addon implementation at readthedocs/addons#431, and I like this implementation more since it follows the pattern we already have and it doesn't require complicated HTTP headers.

[agjohnson]

The feature naming "User JS" could be more accurate I feel, these scripts aren't connected to users, especially on commercial where projects don't really have users -- only teams and members. This feels more like a custom script or extra script or some other phrase that signals usage more.

The script could live in Read the Docs itself using a relative URL, or outside it, using an absolute URL.

I think it's fine to start here.

We might eventually consider doing this automatically for the user though. If we made this field the source of the JS file instead of a URL, we could easily serve the file for the user (under /_/?). This would feel nicer than having the user maintain the JS in one of the project versions and having to rebuild the version (or pushing the file off to a third party host).

[humitos]

This feels more like a custom script or extra script or some other phrase that signals usage more.

I like custom script 👍🏼 . I will update the code with that name.

We might eventually consider doing this automatically for the user though. If we made this field the source of the JS file instead of a URL, we could easily serve the file for the user (under /_/?). This would feel nicer than having the user maintain the JS in one of the project versions and having to rebuild the version (or pushing the file off to a third party host).

Yeah, that makes sense to me. I didn't want to complicate things by uploading a file, but maybe a TextField is enough? However, it will immediately put a lot more pressure on the Read the Docs side for this. People will start asking for a nicer editor for that field, and also versioning, etc. I think this could escalate pretty quickly. I'm not opposed, but I think we can explore this more in a future iteration.

[agjohnson]

Yeah, I'd say we could explore a textfield, nothing fancy. I don't think we need to take on any additional work around an editor UI or versioning though, that seems like a lot for a minor feature. I'd only take on an editor interface if we had another use for it somewhere else in the UI. I'd sooner allow an API POST to update the addons config and let users manage their project's custom JS that way.

[humitos]

Yeah, I'd say we could explore a textfield, nothing fancy.

Do you mean in this PR or in the next iteration?

[humitos]

Maybe do we want to have both? customscript_src and customscript_content where you can define one or the other?

[agjohnson]

Do you mean in this PR or in the next iteration?

Sorry, yeah later, I think it's fine to start with just a URL

Maybe do we want to have both?

Great point, supporting both doesn't seem hard. This sounds like a good plan for later

[ericholscher]

This is a really nice feature 💯. If we're gonna ship it, we should put some docs together, and probably a couple examples of when this is useful.

[ericholscher]

Nice making them nullable 💯

[stsewd]

customscript_enabled is not nullable, so this will still break when creating a new addons object.

[ericholscher]

The previous migration makes it nullable during deploy, and then marks it not nullable after, which I thought would work?

[stsewd]

ah, I didn't see there were two migrations. I guess Django will ask for a default value when running this migration (for the objects that were created while the field was null).

[humitos]

If we're gonna ship it, we should put some docs together, and probably a couple examples of when this is useful.

I'm gonna merge this PR and the addons one. However, this won't be exposed to users until we write the UI in ext-theme. I will create issues for these tasks.