Removing JavaScript Dependencies #10070
Comments
|
Looping in some Read the Docs folks: @ericholscher & @nienn: Do you have any advice or can you provide any intel based on RTD usage? For example, we could check the most important extensions and themes, based on RTD usage stats. Thank you. |
|
From a quick look, the only usage in https://github.com/sphinx-doc I can see 1 is https://github.com/sphinx-doc/sphinxcontrib-websupport/blob/master/sphinxcontrib/websupport/files/websupport.js Popular/impactful themes -- I'd probably suggest looking at at least:
Actual data would of course be more helpful! A Footnotes
|
|
I can confirm that Furo doesn't depend on jQuery or UnderscoreJS. |
|
Thanks! I forgot that there is a separate org for many extensions: https://github.com/sphinx-contrib/ (I do not have access to the new GitHub code search feature, yet.) |
|
Doing a search on sphinx-contrib brings up references in There's a total of 10 results, all in these two. Okay, there's one in zopeext but that's in an HTML file. |
|
I now have access to GitHub code search and found these two extensions that use jQuery:
|
|
@TimKam Sadly we don't have great stats on extension usage across the platform. This is something we hope to figure out eventually, but not something we have currently. |
|
Thanks, @ericholscher. Let us know if there's anything we need to consider from RTD's perspective when removing jQuery and underscore. @tk0miya I think many templates will break if we don't announce this carefully. Should we add an info message when building or something similar? |
|
I don't have good idea to let developers know the deprecation. But info or message warnings on build would not help it, I think. So it would be better to announce it on CHANGES file and sphinx-users group. |
|
An idea I had is (attempting to) patch the actual jQuery object itself in JS, and warn on any method access. I don't think it's great though, as it relies on users checking the JS console. Agree with @tk0miya on adding notes to CHANGES etc -- my initial PR at #10028 does this, although maybe it could be called out more? A |
|
https://github.com/wpilibsuite provides several popular extensions and we are tracking this change. Not sure when we'll make the change, but we'll get to it. |
|
I've noticed Search results are quite broken, one can see it also on the official website: https://www.sphinx-doc.org/en/master/search.html?q=--keep-going I see the section What was displayed before: Moreover, the following is also bad: |
|
@marxin looking at the console output at least part of the problem is that read the docs' overwriting of Sphinx search isn't fixed yet -- does the problem persist on 'pure' Sphinx?
A |
Dunno. Is there a bug report about the RTD issue, please? |
|
And I have a project where it fails with |
|
@marxin I'm trying to fix all things related to search on latest sphinx and rtd, I'm tracking the progress at readthedocs/readthedocs.org#8871. |
In that project, https://splichal.eu/scripts/sphinx/demo/_build/html/searchindex.js doesn't have Sorry to ask for more things, I'm just trying to find where the error is -- the stemmer, the index, A |
Sure, there's a version built with |
|
It's better, but still not ideal: Note |
|
Note you can use the following Demo project for testing: |
|
@AA-Turner Can you please take a look at the attached demo project and investigate what's wrong? Thanks. |
I went ahead and did this manually in a dirty way to, at least, have these numbers 😄
Note this data belongs to projects that were built at least once starting in mid-May (when we started collecting this data) and the repository name does not always match the PyPI package name. I hope this data is useful to make better decisions. |
|
Hi all! I've been working on analyzing some data we have been collecting on Read the Docs after building the "telemetry" database. That data helps us to answer questions like "What are the most used Sphinx extensions in a period?". I wrote a blog about this at https://blog.readthedocs.com/knowing-more-about-ourselves/ and added this particular plot on it. I think that plot/data could be useful when prioritizing the work required to remove JavaScript dependency and on what extensions work first. Let me know if you find this useful and if you are interested in a particular question that can be answered with the data we have now. Thanks! |
|
Thanks @humitos! Would it be possible to have the extension popularity data in a tabular format? (Eg just pasted in a table here.) We can then look through the most popular and open issues or identify JS deps etc. Thanks, |
|
Ping here @humitos! A |
|
FWIW, I believe @humitos is currently travelling to attend a conference. He might respond during the trip but I figured it can’t hurt to mention this to set expectations. :) |
|
Ahh, thanks Pradyun. This isn't urgent, of course. A |
|
I'm at DjangoConEU and that's why I haven't replied yet. However, I should have mentioned this before, tho 🙂 I plan to come back to this issue next week and upload the data requested with more information about the filters used to get it. |
|
Hey @AA-Turner! I'm back to work and I executed the query for the following statement:
Raw query SELECT
COUNT(DISTINCT data->'project'->'id') AS projects,
item->>'name' AS name
FROM
"telemetry_builddata",
LATERAL jsonb_path_query(data, '$.packages.pip.all ? (@.name like_regex "^(sphinxcontrib|sphinx)-")') item
WHERE
created BETWEEN '2022-08-01' AND '2022-09-01'
GROUP BY item->>'name'
ORDER BY projects DESC;and these are the results: sphinx-extensions.csv Let me know if this is the correct query you were expecting and if it's helpful for you to make better decisions. |
|
Thank you @humitos, this is really usefull! Do you track package dependency data at all? I.e. package X has a transitive/direct dependency on Sphinx core but might not have "sphinx" in its name. If you don't, I could probably build this data myself but I imagine the CSV file of all dependencies downloaded into RTD is substantially larger! A |
|
The other (top-down) direction would be if you track the contents of the "extensions" or "html_theme" keys in A |
|
Unfortunately, we don't track the package dependency nor the contents of |
The PR I created to track these got merged already. Hopefully, we will have some data about the extensions starting next week 👍🏼 |
|
From @humitos's first list, the following depend on jQuery implicitly. I have checked the entire list and I believe all the others are fine.
A |
|
Sphinx 6.0.0 has been released. A |
JQuery was removed as of Sphinx 6. The maintainers of our theme already reacted to this but the release is not final yet. Ref sphinx-doc/sphinx#10070 Ref readthedocs/sphinx_rtd_theme#1385 Signed-off-by: Richard Steinmetz <[email protected]>
JQuery was removed as of Sphinx 6. The maintainers of our theme already reacted to this but the release is not final yet. Ref sphinx-doc/sphinx#10070 Ref readthedocs/sphinx_rtd_theme#1385 Signed-off-by: Richard Steinmetz <[email protected]>
JQuery was removed as of Sphinx 6. The maintainers of our theme already reacted to this but the release is not final yet. Ref sphinx-doc/sphinx#10070 Ref readthedocs/sphinx_rtd_theme#1385 Signed-off-by: Richard Steinmetz <[email protected]>
JQuery was removed as of Sphinx 6. The maintainers of our theme already reacted to this but the release is not final yet. Ref sphinx-doc/sphinx#10070 Ref readthedocs/sphinx_rtd_theme#1385 Signed-off-by: Richard Steinmetz <[email protected]>
Relates to #10028.
Sphinx plans to remove jQuery and underscore JS dependencies in version 6.0.0 (i.e., eventually, there is plenty of time). This will probably break many extensions and themes and we need to try and find at least the most important ones.
TODOs:
The text was updated successfully, but these errors were encountered: