search

executablebooks / jupyter-book

Create beautiful, publication-quality books and documents from computational content.
http://jupyterbook.org
BSD 3-Clause "New" or "Revised" License
3.77k stars 652 forks source link

Add hypothes.is integration #861

Closed choldgraf closed 3 years ago

choldgraf commented 3 years ago

Hypothes.is is a non-profit organization that builds technology to facilitate conversation across the web. Their primary tool allows you to provide a "commenting and discussion overlay" on top of any website. This can be used either with the full public, or via communities, teams, and classes.

I know that a lot of people use hypothes.is for class material, and I feel like this could be really interesting if we could build in hypothes.is support to Jupyter Book.

The web embedding instructions suggest that it is as simple as including some javascript on a page, and this will allow users to trigger the hypothes.is overlay on the content in the page. We should explore whether and how this could be incorporated into Jupyter Book!

cc @ctb who I believe has used hypothesis before. I am curious if he thinks something like this would be useful for Jupyter Book users.

choldgraf commented 3 years ago

It turns out this was very very easy to do at a minimal level.

All that the extension does is just load the hypothes.is javascript bundle. I wonder if there are other ways that jupyter book could improve this experience? Or is this it?

I kinda feel like if the only integration is just activating a script, this might be better-done with documentation in Jupyter Book...but perhaps there are other ways to integrate the two more deeply.

tfiers commented 3 years ago

I've been using it successfully to have PhD supervisors comment on my research notebooks (unfortunately closed source for now still). Indeed just the JavaScript tag is enough, it works very well

tfiers commented 3 years ago

One thing jupyter book could do: make sphinx meta tag directive work, for Hypothesis document equivalence (i.e. to be resilient to URL changes)

karthik commented 3 years ago

It's very easy to integrate. I'm not sure you can enhance the experience even more. We have it turned on with bookdown at plan.urssi.us

One thing that's super suboptimal about hypothesis is that you cannot delete a comment even as a book owner. Only the author can delete comments, even if the issue has been resolved.

choldgraf commented 3 years ago

@karthik interesting - have you found it to be useful for you as an author? Or for readers? It sounds like technically this would be very easy, the question is more like "would it be worth putting this in front of the 👀 of book authors and making it a button to press and turn on".

I wish there were a way you could connect the hypothes.is UI but the "sources" for the threads would actually be github issues...

karthik commented 3 years ago

have you found it to be useful for you as an author?

Sort of. Outside of Google docs or GitHub, it's an easy way to get inline comments. Only other way to give feedback on a gitbook like entity is to copy paste blocks of text into an email/issue and write feedback below. So in that sense, it is useful.

But as I said above, once resolved, authors/owners cannot dismiss/delete comments. They have to reach out to the original commenter to come back and delete that typo note. So now I have tons of comments that are out of date. :/

But that’s really an issue with hypothesis itself. You should still enable it and let authors decide if they want to use it.

I wish there were a way you could connect the hypothes.is UI but the "sources" for the threads would actually be github issues...

This is a feature in bookdown. See here

image

choldgraf commented 3 years ago

ya the "go to the edit this page UI in github" exists in jupyter book too, I thought it'd be neat if it could be done "within page" using the hypothesis overlay

chrisjsewell commented 3 years ago

One thing that's super suboptimal about hypothesis is that you cannot delete a comment even as a book owner. Only the author can delete comments, even if the issue has been resolved.

Have you opened an issue for this in https://github.com/hypothesis/h

judell commented 3 years ago

I'd be happy to hop on a call to talk about options, @choldgraf, including the problem that @karthik notes.

csarven commented 3 years ago

I'd like to strongly suggest to not focus on a particular tool (because it eventually translates to vendor lock-in) but designs that loosely couple application and data using Web standards.

If you'd like creators to control their own annotations, optionally use public annotation services and decentralised notifications - as opposed to third-party controlled identifiers, resources and proprietary APIs and data - then I suggest servers and clients based on standards eg: https://github.com/linkeddata/dokieli + https://github.com/solid/specification .

You may want to go through this section as to what's possible with dokieli and an ocean of open Web standards at its disposal: https://csarven.ca/linked-research-decentralised-web#decentralised-linked-research-application . Note the decentralised annotation and notification at work in the abstract section of the article https://csarven.ca/linked-research-decentralised-web#decentralised-linked-research-application ie. article is at A, annotation is at B, notification is at C, annotator's WebID at D and so on. Decentralised. Interoperable.

See also https://csarven.ca/linked-research-decentralised-web#hypothes.is and https://csarven.ca/linked-research-decentralised-web#dokieli-hypothes.is for an overview on underlying architectures.

I'd be happy to hop on a call to help you understand the designs and how that can help you make a decision.

choldgraf commented 3 years ago

So, it sounds like there are roughly two ways that Jupyter Book could "support" these kinds of annotation tools.

  1. Make sure that Jupyter Books have good-enough metadata for these tools. Here it sounds like following some w3c standards would be best.
    • From all of the links above it's a bit hard for me to figure out what exactly this means. Is there a short and fast writeup that's just like "here are the 4 things you should do to make your website scrapable / indexable / etc by services like hypothes.is and dokieli"?
    • Does hypothes.is follow whatever web standards are laid out in the articles linked above?
  2. Build in some simple activation / configuration options for specific services.
    • This seems closer to the sphinx-hypothesis extension I demoed above. Perhaps it's be better as a portal into multiple annotation projects, and called sphinx-annotate or something.
    • It would be something like an easy way to activate the extension on pages or for the whole site, as well as some configuration layer for it (e.g. following this website. Does that sound correct @judell ?
    • It seems like this is possible for dokieli as well? I haven't been able to find a super short "just do X,Y,Z and dokieli will be added to your website" guide...perhaps @csarven could advise?
hamelsmu commented 3 years ago

@choldgraf

I wish there were a way you could connect the hypothes.is UI but the "sources" for the threads would actually be github issues...

Not exactly the same as annotations, but we are using Utterances to enable commenting on blog posts in fastpages, and the threads are stored on GitHub issues. Perhaps this could be useful. You can see a live demo by scrolling to the bottom of this blog post.

hamelsmu commented 3 years ago

I really like this option

Build in some simple activation / configuration options for specific services.

As a user of these tools, I would likely not stumble upon this very useful idea unless there is some kind of paved path to gently guide me along the path of enabling these things. I don't see anything wrong with making it simple to activate. I didn't even know about annotation tools until seeing this thread, and now I'm wondering why I haven't been using them for longer!

choldgraf commented 3 years ago

As a user of these tools, I would likely not stumble upon this very useful idea unless there is some kind of paved path to gently guide me

totally - I am thinking something like:

comments:
  disqus:
    key: val
  hypothesis:
    these: configure
  utterances:
    each: comments-engine
  dokieli:
    key: val

As you say, even if it is as simple as just "load this JS library", that is still a step most folks wouldn't (know to) take.

btw - I hadn't heard about utterances before! That is really neat!

choldgraf commented 3 years ago

I am gonna play around with this over here: https://github.com/executablebooks/sphinx-comments (I think "sphinx-comments" is generic enough?). Would love collaboration, ideas, etc! Let me know if somebody would like admin rights on that repo :-)

choldgraf commented 3 years ago

check out a little demo here:

https://predictablynoisy.com/sphinx-comments/

that shows off both utterances + hypothes.is integration. Surprisingly small number of lines of code! 🎉

hamelsmu commented 3 years ago

This is pretty cool!

On Sun, Aug 9, 2020 at 4:14 PM Chris Holdgraf notifications@github.com wrote:

check out a little demo here:

https://predictablynoisy.com/sphinx-comments/

that shows off both utterances + hypothes.is integration. Surprisingly small number of lines of code! 🎉

— You are receiving this because you commented. Reply to this email directly, view it on GitHub https://github.com/executablebooks/jupyter-book/issues/861#issuecomment-671112520, or unsubscribe https://github.com/notifications/unsubscribe-auth/AALKJEWP6RP37USCVAUCNOLR74UVRANCNFSM4PYC74IQ .

csarven commented 3 years ago

Any HTML document can include the following (or a copy of) or inject into the DOM eg. through a browser extension:

    <link href="https://dokie.li/media/css/dokieli.css" media="all" rel="stylesheet" />
    <script src="https://dokie.li/scripts/dokieli.js"></script>

Please take annotator's identifier, storage and notifications locations, and access controls into account. Who ultimately controls them?

choldgraf commented 3 years ago

@csarven thanks for the tip! I've got Dokieli working with it as well ✨ (though it looks like hypothes.is and dokieli JS libraries clash)

Please take annotator's identifier, storage and notifications locations, and access controls into account. Who ultimately controls them?

I am not sure what you mean by this...are these things that I would have control over? Or a book author would have control over?

choldgraf commented 3 years ago

Y'all can check out a sphinx extension that adds support for dokieli, hypothesis, and utterances here: https://sphinx-comments.readthedocs.io/

Next step is to build in an integration with Jupyter Book, but would love feedback on what's there so far!

choldgraf commented 3 years ago

Have a PR to add this functionality here: https://github.com/executablebooks/jupyter-book/pull/866

they all work great except for dokie.li, which seems to contrast with the page's require.js library (it's spitting out a big messy error I have seen before for similar reasons). A preview page of that is here:

https://5f321598920fb700073f077b--jupyter-book.netlify.app/interactive/comments/dokieli.html

cc @csarven in case they know of any reasons this problem would pop up

hamelsmu commented 3 years ago

FWIW - I've merged hypothesis integration into fastpages as well 🎉

csarven commented 3 years ago

Is Line 67 at https://5f321598920fb700073f077b--jupyter-book.netlify.app/interactive/comments/dokieli.html intended:

<meta property="og:description" content="Dokieli  &lt;script src=&#34;https://dokie.li/scripts/dokieli.js&#34;&gt;&lt;/script&gt; &lt;link media=&#34;all&#34; rel=&#34;stylesheet&#34; type=&#34;text/css&#34; href=&#34;https://dokie.li/media/css/dokieli" />

Is require.js a netfly-specific thing? In case it makes any differences, I'd suggest to include the CSS and JS in <head> any way. BTW, dokieli.js has an event listener for DOMContentLoaded.

choldgraf commented 3 years ago

ok gonna close this since we have an "alpha" implementation of this and have https://github.com/executablebooks/sphinx-comments/issues/12 to track the remaining dokieli functionality to add