Description

JulienPalard

opened on Nov 4, 2020

Issue body actions

The doc is fast :)

But can it be faster ? → https://developers.google.com/speed/pagespeed/insights/?url=https%3A%2F%2Fdocs.python.org

Typically we load jquery and a few other libs, and we load them soon so they may block the rendering of the page. I think this can be enhanced, but I'm myself particularly bad at front-end things, so if someone want to handle it, go for it :)

Activity

1. pradyunsg commented on Nov 13, 2020

   

   pradyunsg

   on Nov 13, 2020

   Member

   More actions

   The jQuery load comes from Sphinx directly.

   A bunch of external Sphinx plugins directly depend on the jQuery being loaded on every page, so "simply" removing it is going to cause issues if any downstream users want to use them (ReadTheDocs also depends on jQuery for example). :(

   sphinx-doc/sphinx#7405 is the relevant issue upstream.

   One option at hand is having a theme option to opt-in to disabling jQuery on all pages. This'll allow for faster page load times for users who care (like docs.python.org). :)
2. pradyunsg commented on Nov 13, 2020

   

   pradyunsg

   on Nov 13, 2020

   Member

   More actions

   Also, there's parts of this theme that also similarly assume that jQuery is available (I just spotted $('.inline-search').show(0);).
3. methane commented on Nov 14, 2020

   

   methane

   on Nov 14, 2020

   Member

   More actions

   I think most JavaScript files can be "defer" ed.
   Another problem is sidebar.js. It is ad-hock hack. It changes layout so redraw happens. User will see sidebar is vibrating on load.
4. methane commented on Nov 14, 2020

   

   methane

   on Nov 14, 2020

   Member

   More actions

   Can we have some simple CSS compiler? We have 5 css files now, but they can be concatinated.

   https://developers.google.com/speed/pagespeed/insights/?url=https%3A%2F%2Fdocs.python.org%2F3%2Flibrary%2Fstdtypes.html
5. methane commented on Nov 14, 2020

   

   methane

   on Nov 14, 2020

   Member

   More actions

   I find language_data.js is used from only searchtools.js, which is included only from search.html.
   But language_data.js is loaded all pages.
6. pradyunsg commented on Nov 14, 2020

   

   pradyunsg

   on Nov 14, 2020

   Member

   More actions

   @methane yes, but we can’t be sure of the order of execution then.

   There are various implicit dependencies (eg: extensions depending on jQuery,search tools depending on jQuery etc) that are only satisfied by the order that Sphinx gives the files in, which makes deferring not an option that can be used generally in the context of Sphinx documentation.

   I’ve tried to do that, and failed, while writing my own documentation theme (Furo).
7. methane commented on Nov 15, 2020

   

   methane

   on Nov 15, 2020

   Member

   More actions

   https://developer.mozilla.org/en-US/docs/Web/HTML/Element/script

   Scripts with the defer attribute will execute in the order in which they appear in the document.

   So we can be sure the order of execution.
8. pradyunsg commented on May 1, 2021

   

   pradyunsg

   on May 1, 2021

   Member

   More actions

   So we can be sure the order of execution.

   Indeed! I stand corrected. :)

   Your comment made me add this to Furo (https://pradyunsg.me/furo/changelog/?highlight=script#beta17), but I've had to subsequently remove it (https://pradyunsg.me/furo/changelog/?highlight=script#beta25) because Sphinx search and other extensions were breaking in a subtle way.

   ---

   I'll reiterate what I was trying to say earlier -- the issue is not the Sphinx can't generate pages with this, or that web browsers don't support these things -- but rather that nearly every part of Sphinx's ecosystem assumes that jQuery is available, and that jQuery is hard-coded into the Sphinx's HTML "builder" (https://github.com/sphinx-doc/sphinx/blob/4.x/sphinx/builders/html/__init__.py#L315); so overriding it will require weird hacky logic in the HTML templates to avoid including it and things will break in subtle ways.

   I don't think this would be easy and, personally, don't think that it'd be worth it; especially given the tiny amounts of volunteer time available for this theme. None the less, I'm not going to be doing this and was mostly just providing a cautionary bit of guidance based on my experience. I'll defer to y'all to decide on this. :)
9. methane commented on May 1, 2021

   

   methane

   on May 1, 2021

   Member

   More actions

   I didn't mean using defer for jQuery. I meant most JavaScripts other than jQuery.
10. m-aciek commented on Mar 13, 2023

    

    m-aciek

    on Mar 13, 2023

    Contributor

    More actions

    For what it's worth this PR contains changes that get rid of jQuery in favor of pure JavaScript (assuring compatibility with most recent Sphinx versions).
11. AA-Turner commented on Apr 20, 2023

    

    AA-Turner

    on Apr 20, 2023

    Member

    More actions

    #99 now merged! Updating to a jQuery-less Sphinx seems like it'll save ~four fifths of the total page JavaScript, see this Lighthouse report.

    A

    Reacted by Hugo van Kemenade, Pradyun Gedam, Julien Palard and Maciej Olko
12. Privat33r-dev commented on Mar 17, 2024

    

    Privat33r-dev

    on Mar 17, 2024

    Contributor

    More actions

    
    I guess the issue is resolved at this point?

    Reacted by Julien Palard
13. JulienPalard

    closed this as completedon Mar 18, 2024

Issue actions