Embed APIv3: use latest embed API version by humitos · Pull Request #146 · readthedocs/sphinx-hoverxref

humitos · 2021-09-22T13:16:12Z

This PR makes usage of the Embed APIv3 that's going to be available in Read the Docs soon. It mainly changes how the API URL is generated. Instead of reading arguments (data-*) injected at build time by Python, it uses only one url= argument which is retrieved from the a.href property via Javascript on hover event.

Note that this reduces the complexity of the Python code a lot since we don't need to resolve references and hard code them into data-* attributes anymore.

ToDo

~~find a way to send the full URL to EmbedAPI (from Python code we can't know the hosted URL)~~
write tests
remove all code for other data- elements?
remove hardcoded URL
remove hardcoded backend api host pointing to ngrok
remove restriction about "must be hosted on Read the Docs" to work from the intersphinx docs
update documentation
remove hoverxref_project and _version to be required
QA making sure that all tooltips/links work

Related readthedocs/readthedocs.org#8521

`data['content']` returned by the API is not a single string (not a list) --so, we need to tell tooltipster to show it as HTML https://www.heteroclito.fr/modules/tooltipster/#options

The content returned changed from being a list of one element to just a string.

Borrowed from #144

ericholscher

Looks like a good approach, and much simpler 👍

Might be worth doing a call with @readthedocs/frontend folks to see if there's anywhere to collaborate with the UX while doing some release testing.

We are not using `data-` attributes anymore. Everything is based on `class=` and `href=` attributes from the elements. `hoverxref_project` and `hoverxref_version` are not required anymore and they are deleted as well.

ericholscher

This looks like a way nicer way to integrate things. Really glad to see this simplified.

Do we have a release plan for this code documented anywhere? I guess we can install it via git directly to test if we want, but doing some kind of beta release to pypi might be interesting.

ericholscher · 2021-09-27T17:25:45Z

-hoverxref_api_host = 'https://readthedocs.ngrok.io'
+if os.environ.get('NGROK_READTHEDOCS') == 'True':
+    # Building on a local Read the Docs instance using NGROK for HTTPS
+    hoverxref_api_host = 'https://readthedocs.ngrok.io'


Shouldn't this value get pulled from the environment, so other people can use it if needed in dev? eg NGROK_HOVERXREF= https://foo.ngrok.io.

Haha! Yes! I don't know why I didn't do it like you are suggesting originally 🙃 It should probably just use hoverxref_api_host all in uppercase.

I suppose that I hardcoded it here so I don't have to remember the different URL options 😄

ericholscher · 2021-09-27T17:26:27Z

+     Its default should be fine to build the documentation and make it work in Read the Docs.

-   Default: It defaults to ``READTHEDOCS_VERSION`` environment variable
+   Default: ``https://readthedocs.org``


How are we planning to support this on .org & .com? Should we do this automagically, or just always default to .org?

Hrm... good question!

I haven't thought about this, honestly. I don't think we have a way to differentiate if we are running in .org or .com from the builder. It may be good to expose an environment variable? In that case, we can use it to differentiate.

Actually... I just remembered that @stsewd already mentioned this in #134 --so, we should probably continue the conversation there, finish that PR, and merge it. I think it was good, but there was an issue with CORS that I don't remember where we ended up.

humitos · 2021-09-27T19:16:56Z

Do we have a release plan for this code documented anywhere? I guess we can install it via git directly to test if we want, but doing some kind of beta release to pypi might be interesting.

I was planning to release a 0.8b1 once this and .org branches get merged. I did a bunch of tests locally and everything worked. So, I'm not expecting too many issues --but we will really know once we do the release.

Once we have that release being used for months, I thought we could start thinking about having a 1.0 version; which I think we are close to regarding features and bugs. I don't see too many issues or requested features still around.

humitos added 7 commits September 22, 2021 15:14

Embed APIv3: use latest embed API version

e375975

Update dependencies and docs building

c04238c

Log not found URIs

bdc8e1d

Define type for 'obj' role

68b16b4

Hit local development installation for now

51760a5

Hardcode hosted URL for now

fea2a5b

Use ngrok because HTTPS

e463808

humitos force-pushed the humitos/embed-api-v3 branch from fb63f85 to e463808 Compare September 22, 2021 13:50

humitos added 2 commits September 22, 2021 15:58

Show content as HTML

a4d0aaf

`data['content']` returned by the API is not a single string (not a list) --so, we need to tell tooltipster to show it as HTML https://www.heteroclito.fr/modules/tooltipster/#options

Show proper content in modal instead of first char

64f7d3d

The content returned changed from being a list of one element to just a string.

humitos mentioned this pull request Sep 22, 2021

EmbedAPIv3: updates after QA with sphinx-hoverxref readthedocs/readthedocs.org#8521

Merged

humitos added 2 commits September 22, 2021 17:40

Hack the title to remove extra icon

5cfbc3b

Add a comment about permalink icon

56beaf4

humitos force-pushed the humitos/embed-api-v3 branch from 63bd0d8 to c8d8016 Compare September 23, 2021 10:23

Use element.href if data-url is not present

171920a

humitos force-pushed the humitos/embed-api-v3 branch from c8d8016 to 171920a Compare September 23, 2021 10:27

humitos commented Sep 23, 2021

View reviewed changes

Comment thread hoverxref/_static/js/hoverxref.js_t

humitos commented Sep 23, 2021

View reviewed changes

Comment thread hoverxref/domains.py Outdated

humitos added 2 commits September 23, 2021 19:01

Add some intersphinx external examples and minor details

0096aee

reftype fallbacks

af03ce8

Borrowed from #144

humitos force-pushed the humitos/embed-api-v3 branch from 5a1efe2 to af03ce8 Compare September 23, 2021 17:02

ericholscher reviewed Sep 23, 2021

View reviewed changes

Comment thread docs/conf.py Outdated

Comment thread hoverxref/domains.py Outdated

Remove all data- attributes code

e17b9b7

We are not using `data-` attributes anymore. Everything is based on `class=` and `href=` attributes from the elements. `hoverxref_project` and `hoverxref_version` are not required anymore and they are deleted as well.

humitos mentioned this pull request Sep 27, 2021

Improve how JS client removes the last char from the tooltip's title #148

Open

humitos added 6 commits September 27, 2021 09:59

Remove un-needed conf --the default is used

128a491

Minor updates

1b7787a

Update build badge

a99bb7b

Update documentation

8b0c706

Remove un-used functions

6532887

Env variable for NGROK usage

cf1c8b2

humitos marked this pull request as ready for review September 27, 2021 08:59

humitos requested review from a team and ericholscher September 27, 2021 09:01

humitos mentioned this pull request Sep 27, 2021

Support glossary / term and sphinxcontrib-bibtex #149

Merged

ericholscher approved these changes Sep 27, 2021

View reviewed changes

humitos mentioned this pull request Sep 27, 2021

requirements: update Sphinx and sphinx-rtd-theme #147

Closed

humitos merged commit 7ceefee into master Sep 28, 2021

humitos deleted the humitos/embed-api-v3 branch September 28, 2021 10:48

humitos mentioned this pull request Sep 28, 2021

Intersphinx - RefType - Use objtypes inventory as fallback mechanism #144

Closed

humitos mentioned this pull request Aug 29, 2023

Embed API: fully deprecate/remove embed API V2 readthedocs/readthedocs.org#10677

Closed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Embed APIv3: use latest embed API version#146

Embed APIv3: use latest embed API version#146
humitos merged 21 commits intomasterfrom
humitos/embed-api-v3

humitos commented Sep 22, 2021 •

edited

Loading

Uh oh!

Uh oh!

Uh oh!

ericholscher left a comment

Uh oh!

Uh oh!

Uh oh!

ericholscher left a comment

Uh oh!

ericholscher Sep 27, 2021

Uh oh!

humitos Sep 27, 2021

Uh oh!

humitos Sep 27, 2021

Uh oh!

ericholscher Sep 27, 2021

Uh oh!

humitos Sep 27, 2021

Uh oh!

Uh oh!

humitos commented Sep 27, 2021

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Conversation

humitos commented Sep 22, 2021 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

ToDo

Uh oh!

Uh oh!

Uh oh!

ericholscher left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

ericholscher left a comment

Choose a reason for hiding this comment

Uh oh!

ericholscher Sep 27, 2021

Choose a reason for hiding this comment

Uh oh!

humitos Sep 27, 2021

Choose a reason for hiding this comment

Uh oh!

humitos Sep 27, 2021

Choose a reason for hiding this comment

Uh oh!

ericholscher Sep 27, 2021

Choose a reason for hiding this comment

Uh oh!

humitos Sep 27, 2021

Choose a reason for hiding this comment

Uh oh!

Uh oh!

humitos commented Sep 27, 2021

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

humitos commented Sep 22, 2021 •

edited

Loading