Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add floating window tooltips for cross-references in the docs #3083

Merged

Conversation

agriyakhetarpal
Copy link
Member

Description

This PR adds and configures support for sphinx-hoverxref, which enables hovering over classes, methods, and other links to directly display their results within the same page

Type of change

Please add a line in the relevant section of CHANGELOG.md to document the change (include PR #) - note reverse order of PR #s. If necessary, also add to the list of breaking changes.

  • New feature (non-breaking change which adds functionality)
  • Optimization (back-end change that speeds up the code)
  • Bug fix (non-breaking change which fixes an issue)

Key checklist:

  • No style issues: $ pre-commit run (see CONTRIBUTING.md for how to set this up to run automatically when committing locally, in just two lines of code)
  • All tests pass: $ python run-tests.py --all
  • The documentation builds: $ python run-tests.py --doctest

You can run unit and doctests together at once, using $ python run-tests.py --quick.

Further checks:

  • Code is commented, particularly in hard-to-understand areas
  • Tests added that prove fix is effective or that feature works

@codecov
Copy link

codecov bot commented Jun 29, 2023

Codecov Report

Patch and project coverage have no change.

Comparison is base (5e28bb9) 99.71% compared to head (eac5cf1) 99.71%.

❗ Current head eac5cf1 differs from pull request most recent head f890dbb. Consider uploading reports for the commit f890dbb to get more accurate results

Additional details and impacted files
@@           Coverage Diff            @@
##           develop    #3083   +/-   ##
========================================
  Coverage    99.71%   99.71%           
========================================
  Files          248      248           
  Lines        18749    18749           
========================================
  Hits         18695    18695           
  Misses          54       54           

☔ View full report in Codecov by Sentry.
📢 Do you have feedback about the report comment? Let us know in this issue.

This should fix the appearance of the tooltips on the light theme.

Increases the max width to 750 pixels and adds animations too
@agriyakhetarpal
Copy link
Member Author

It turns out that dark mode support is not available yet: readthedocs/sphinx-hoverxref#231, which means either one of the light or dark themes breaks: the tooltipster-punk option1 looks good on the dark theme but not on the light theme, while the default one, i.e., tooltipster-shadow2 breaks on the dark theme. @tinosulzer, which one we should go with?

Footnotes

  1. An example is on the built docs, currently using the tooltipster-punk theme

  2. sphinx-hoverxref documentation usage example

@valentinsulzer
Copy link
Member

Can you look into the suggested solution with css?

@agriyakhetarpal
Copy link
Member Author

agriyakhetarpal commented Jun 30, 2023

It should look fine now on both light and dark themes. The unit tests are failing because Pydantic had a v2 release a few hours ago, which broke bpx

Copy link
Member

@Saransh-cpp Saransh-cpp left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This looks amazing, thanks @agriyakhetarpal!

Also, we are currently redirecting users to scipy's user guide - the text available under API documentation. Caught this using the tooltip haha! Maybe that can be fixed in this PR.

instead of the SciPy user guide
@agriyakhetarpal
Copy link
Member Author

Good catch, thanks! Fixed it, though this is very strange and should not happen – I can file a bug report in the sphinx-hoverxref repository in case we find any more issues like this

@valentinsulzer valentinsulzer merged commit e6eaa7c into pybamm-team:develop Jul 5, 2023
14 of 19 checks passed
@agriyakhetarpal agriyakhetarpal deleted the sphinx-hoverxref branch July 5, 2023 12:06
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

None yet

3 participants