search

executablebooks / sphinx-book-theme

A clean book theme for scientific explanations and documentation with Sphinx
https://sphinx-book-theme.readthedocs.io
BSD 3-Clause "New" or "Revised" License
431 stars 197 forks source link

Remove JQuery and update versions #668

Closed choldgraf closed 1 year ago

choldgraf commented 1 year ago

This adds support for much of the latest versions of our dependencies, and also removes JQuery since it is now removed in the latest version of Sphinx.

Todo

References

choldgraf commented 1 year ago

@AakashGfude could you have a look at this one?

mathbunnyru commented 1 year ago

Thanks! The title is visible now, but it intersects with the search bar.

Screenshot 2023-01-07 at 18 21 07
mathbunnyru commented 1 year ago

Also, may I ask you to build a new rc version when this is merged? I will try it out in our repo and will tell you if something goes wrong.

choldgraf commented 1 year ago

Hmm if you need this quickly it may need to be split into multiple PRs. This currently builds off of main for the pydata theme, so we'd need to wait for a release there.

mathbunnyru commented 1 year ago

No pressure here, we're not in a hurry at all :) I just wanted to emphasize that after these changes, I will probably be quite happy with the new release and if needed, will do one more detailed comparison to see what's not working in our docs.

consideRatio commented 1 year ago

@mathbunnyru you can also install from the branch directly if you want to experiment i think!

I always end up googling how though, but i think @choldgraf may have a blogpost about it? 😅🥰

mathbunnyru commented 1 year ago

I actually tried it once locally and it didn't work for me on my m2 mac. I will try once again, when I have time :)

mathbunnyru commented 1 year ago

A few more differences I found with this PR (I compared it with the previous one):

It now adds ; after Copyright sign.

Screenshot 2023-01-08 at 14 40 51

Code blocks highlighting looks different. already merged pr: https://sphinx-book-theme--669.org.readthedocs.build/en/669/notebooks.html#code-blocks-and-image-outputs this pr: https://sphinx-book-theme--668.org.readthedocs.build/en/668/notebooks.html#code-blocks-and-image-outputs

This page is not rendered properly at all - images and dataframes are missing, interactive part is also gone.

AakashGfude commented 1 year ago

Thanks! The title is visible now, but it intersects with the search bar.

Screenshot 2023-01-07 at 18 21 07

Is the title purposefully made visible?

EDIT: Ok, got it, based on this issue: https://github.com/executablebooks/sphinx-book-theme/issues/672

AakashGfude commented 1 year ago

Something crazy happened in Sphinx extension styles page: https://sphinx-book-theme--668.org.readthedocs.build/en/668/reference/extensions.html

Screen Shot 2023-01-09 at 12 08 03 pm

But the same problem is in the production page as well: https://sphinx-book-theme.readthedocs.io/en/latest/reference/extensions.html . I reckon the sphinx-tabs extension is interfering with something.

choldgraf commented 1 year ago

Another idea we had re: pinning versions was the following, curious what you think as well @consideRatio :

I also opened an issue in sphinxcontrib-bibtex to see if they'd like the message in there, but it might be easier to do it here in the short term:

consideRatio commented 1 year ago

I think its good if a package can declare what versions won't work in requirements directly, and ideally while avoiding placing upper bound that needs to be removed in the future. But, if one doesn't know in what release something is patched, one kind of have to. If we know it will be resolved in 0.20 but not in 0.18 and 0.19 etc, then I think this is what to go for if this works >=0.17,!=0.19.*,!=0.20.*

I didn't understand the options about providing messages @choldgraf, but I'd like to avoid digging into this further since I have many balls in the air atm.

AakashGfude commented 1 year ago

It now adds ; after Copyright sign. Screenshot 2023-01-08 at 14 40 51

this semicolon is coming from pydata: https://github.com/pydata/pydata-sphinx-theme/blob/main/src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/copyright.html#L7. So, we need to fix it there.

AakashGfude commented 1 year ago
  • [x] Why are there no outputs on this page, make sure build is working correctly.

The outputs are working now.

mmcky commented 1 year ago

Thanks @AakashGfude for your work on this. I did a review of the rendered docs pages as a second check and here are a few minor things I noticed:

  1. A couple of cells have some highlighting in them that I am not sure where that comes from. Such as the one below that is highlighting the 3 and 4 in blue from https://sphinx-book-theme--668.org.readthedocs.build/en/668/contributing/tests.html
Screenshot 2023-01-31 at 11 48 54 am
  1. Where do these gray lines come from next to the math?
Screenshot 2023-01-31 at 11 54 25 am
AakashGfude commented 1 year ago

@mmcky @choldgraf this build with sphinx5 and docutils0.17 works well with pydata-sphinx-theme==0.12.0 as well (the latest stable release). Should we just use that? It does not have issues like "Extra ; after copyright symbol" etc as well.

choldgraf commented 1 year ago

@AakashGfude I'd suggest using the pydata latest version, because it's going to release a new version very soon:

Do those issues show up there as well?

choldgraf commented 1 year ago

FYI - the pydata-sphinx-theme has a release candidate out! Check it out here:

@AakashGfude I see what you were saying about the missing ; not being present on 0.12, but being present on 0.13. I guess it's a question of whether we want to create another version bump w/ breaking changes relatively quickly after the next release. It seems sub-optimal, but I think if you really wanna get this one out the door, I'm fine just going for it and fixing up bugs in another PR.

AakashGfude commented 1 year ago

Thanks @choldgraf, I will update the version in a new PR once 0.13 Is released and reiterate if UX issues. Hopefully, should not be a lot.