From cbacdecb1e47cda02d8511869386c988591e6e11 Mon Sep 17 00:00:00 2001 From: Min RK Date: Wed, 19 Apr 2023 12:27:17 +0200 Subject: [PATCH] update sharing faq for 2023 --- docs/source/conf.py | 1 + docs/source/faq/faq.md | 90 ++++++++++++++++++------- docs/source/images/shareable_link.webp | Bin 0 -> 8304 bytes 3 files changed, 66 insertions(+), 25 deletions(-) create mode 100644 docs/source/images/shareable_link.webp diff --git a/docs/source/conf.py b/docs/source/conf.py index c3c3958b..6982f40b 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -201,6 +201,7 @@ intersphinx_mapping = { "python": ("https://docs.python.org/3/", None), "tornado": ("https://www.tornadoweb.org/en/stable/", None), "jupyter-server": ("https://jupyter-server.readthedocs.io/en/stable/", None), + "nbgitpuller": ("https://nbgitpuller.readthedocs.io/en/latest", None), } # -- Options for the opengraph extension ------------------------------------- diff --git a/docs/source/faq/faq.md b/docs/source/faq/faq.md index 8aa33b67..a1df47e0 100644 --- a/docs/source/faq/faq.md +++ b/docs/source/faq/faq.md @@ -2,35 +2,75 @@ ## How do I share links to notebooks? -In short, where you see `/user/name/notebooks/foo.ipynb` use `/hub/user-redirect/notebooks/foo.ipynb` (replace `/user/name` with `/hub/user-redirect`). - Sharing links to notebooks is a common activity, -and can look different based on what you mean. +and can look different depending on what you mean by 'share.' Your first instinct might be to copy the URL you see in the browser, -e.g. `hub.jupyter.org/user/yourname/notebooks/coolthing.ipynb`. -However, let's break down what this URL means: +e.g. `jupyterhub.example/user/yourname/notebooks/coolthing.ipynb`, +but this usually won't work, depending on the permissions of the person you share the link with. -`hub.jupyter.org/user/yourname/` is the URL prefix handled by _your server_, -which means that sharing this URL is asking the person you share the link with -to come to _your server_ and look at the exact same file. -In most circumstances, this is forbidden by permissions because the person you share with does not have access to your server. -What actually happens when someone visits this URL will depend on whether your server is running and other factors. +Unfortunately, 'share' means at least a few things to people in a JupyterHub context. +We'll cover 3 common cases here, when they are applicable, and what assumptions they make: -**But what is our actual goal?** +1. sharing links that will open the same file on the visitor's own server +2. sharing links that will bring the visitor to _your_ server (e.g. for real-time collaboration, or RTC) +3. publishing notebooks and sharing links that will download the notebook into the user's server -A typical situation is that you have some shared or common filesystem, -such that the same path corresponds to the same document -(either the exact same document or another copy of it). -Typically, what folks want when they do sharing like this -is for each visitor to open the same file _on their own server_, -so Breq would open `/user/breq/notebooks/foo.ipynb` and -Seivarden would open `/user/seivarden/notebooks/foo.ipynb`, etc. +### link to the same file on the visitor's server -JupyterHub has a special URL that does exactly this! -It's called `/hub/user-redirect/...`. -So if you replace `/user/yourname` in your URL bar -with `/hub/user-redirect` any visitor should get the same -URL on their own server, rather than visiting yours. +This is for the case where you have JupyterHub on a shared (or sufficiently similar) filesystem, where you want to share a link that will cause users to login and start their _own_ server, to view or edit the file. -In JupyterLab 2.0, this should also be the result of the "Copy Shareable Link" -action in the file browser. +**Assumption:** the same path on someone else's server is valid and points to the same file + +This is useful in e.g. classes where you know students have certain files in certain locations, or collaborations where you know you have a shared filesystem where everyone has access to the same files. + +A link should look like `https://jupyterhub.example/hub/user-redirect/lab/tree/foo.ipynb`. +You can hand-craft these URLs from the URL you are looking at, where you see `/user/name/lab/tree/foo.ipynb` use `/hub/user-redirect/lab/tree/foo.ipynb` (replace `/user/name/` with `/hub/user-redirect/`). +Or you can use JupyterLab's "copy shareable link" in the context menu in the file browser: + +![copy shareable link in JupyterLab](../images/shareable_link.webp) + +which will produce a correct URL with `/hub/user-redirect/` in it. + +### link to the file on your server + +This is for the case where you want to both be using _your_ server, e.g. for real-time collaboration (RTC). + +**Assumption:** the user has (or should have) access to your server. + +**Assumption:** your server is running _or_ the user has permission to start it. + +By default, JupyterHub users don't have access to each other's servers, but JupyterHub 2.0 administrators can grant users limited access permissions to each other's servers. +If the visitor doesn't have access to the server, these links will result in a 403 Permission Denied error. + +In many cases, for this situation you can copy the link in your URL bar (`/user/yourname/lab`), or you can add `/tree/path/to/specific/notebook.ipynb` to open a specific file. + +The [jupyterlab-link-share] JupyterLab extension generates these links, and even can _grant_ other users access to your server. + +[jupyterlab-link-share]: https://github.com/jupyterlab-contrib/jupyterlab-link-share + +:::{warning} +Note that the way the extension _grants_ access is handing over credentials to allow the other user to **_BECOME YOU_**. +This is usually not appropriate in JupyterHub. +::: + +### link to a published copy + +Another way to 'share' notebooks is to publish copies, e.g. pushing the notebook to a git repository and sharing a download link. +This way is especially useful for course materials, +where no assumptions are necessary about the user's environment, +except for having one package installed. + +**Assumption:** The [nbgitpuller](inv:nbgitpuller#index) server extension is installed + +Unlike the other two methods, nbgitpuller doesn't provide an extension to copy a shareable link for the document you're currently looking at, +but it does provide a [link generator](inv:nbgitpuller#link), +which uses the `user-redirect` approach above. + +When visiting an nbgitpuller link: + +- The visitor will be directed to their own server +- Your repo will be cloned (or updated if it's already been cloned) +- and then the file opened when it's ready + +[nbgitpuller]: https://nbgitpuller.readthedocs.io +[nbgitpuller-link]: https://nbgitpuller.readthedocs.io/en/latest/link.html diff --git a/docs/source/images/shareable_link.webp b/docs/source/images/shareable_link.webp new file mode 100644 index 0000000000000000000000000000000000000000..e258f3cc73d88b1c5dc7a8fe6cb3792037c539a6 GIT binary patch literal 8304 zcmV-$AdlZtNk&F!AOHYYMM6+kP&iCmAOHX_DFJN&^M-!4JRu6S$W!C66^(O2`_Qyv-bgZT=>gIqepX5fp3u4{kxfwqMNr=UKar$- z4&BUJKbwY;;B~CaEWv{ZA3+K|t-J63A7iQR!QCB3koB!uEQ59MLYk-W!i&|OQ`6o5 ze{I~nb7#;KA4oyP@o;=<@E7zita3QM3ke)%rm&c|D zC%ONyXxoa~oF_CAv`?IUGUd|`mwY82{j$eO?$wba6U9n7+$WUFxISmfuozVfKiaj^ zl_4Fx6EYA8C$FE(9o=z(X}Xh!zkqXzq)j5lP9UJVF>&gJaxlTUm$?qq5WpP)mQFfACmD#eM4^&$;o5mUPxY6HNH!+F zhn5K;)mfYut28PXwgpJI3}z}Xg-F&+6{E;V((iSaZYJXPE|@U31vVxJC~Sms+_1#L z4GV6nZW_5n@@CVt#6lArEeW^16J$d^6xPu;O-mABf3XPO346eF;YN{~T=Z57)dJh~ z&8BHuW=& z=*EVYgxje+$2uAgO$@w=-5HcPY=43Cl(40aHP1GX@+!Kpl0d1+|` z8$hZNfMRKfrk`6iJi*H(JSR3dmFFx^{6W9~`wdzWoPdn^8J3h0loog&LtCG?bWPbSjz5f^^QM8aYy!5l- z#Nvr$=>cM-I8Pg;LbnXKBuwy5EiH;^x)b465VmGb8eodOq%c6LqC*5p-Bh02c(O~J zk^@0U3BR;MITY#w&xP=hunQ1*8z_jOA%#!^Lz&Fbalm<!%?&t%vUfD9?eDP$44 zhLV2)nM`{!Gn7#iGD!icQ-D*(FqE7DoXB7@sb*vX@02k#C-((-Oj9QuM-j|{!9mL4 zU_9V|Uj)c0g}Mxp_I5g5of7yQd=`}9aZXXfcDEVMmPlM}cmeDR!>7Q>Fg$#vs=yGn z8F>qEAor^WLu)X5L9^me6E8!Aa|J{hgw!PCii@JGV0Dnq$-RKGA0&skR&gfG1|)HX zT=A|^l;d@E>T(@7$haC*%3V}5R~LzI&afpO;A9;{Qpa_aTK}{ckOXRx`?5&%x0u~qA|yV4N+7a z5-9N_;WB64y?0DAl@};m2^AJWuuU_jaZY#;LZCP#!y=wg*-FWL&=U;hK*@C`C_PEL zUbiI<4Rv@JgX2q07VP4Xh#F7}5oIfJss$XeEv{XH;aEKS&IITBTZn?&F`@#|gdn19 zrL<|92t(WGX>KNyu$?%sAU!9G7=wnlTJL2zY?tu|uH5Kn-IT z$h;Le-zerKE%L31D>pmFb%_`b7bek|(2jPh|hKQ3@FQOL5;)`9B?7aoDHkxP;JB}+RX6IPWkp6OmDNW z@bUydX;Gxim@s~lF;TMTF3J7Gg)6fOiCf+>%IE3AK4VrQWWxnTuHnzA;uOJHP$YH; zW6sN#4XzLoa3YZ`Fks2X%bzz#o7g)cATvV!8!|J0qi{;RLmtk1Q?n>cT-dKq zM43pQaAEG8x@-CHo=O#ptgtX&?}fjG!tuc$zz(qVe-whB%%hWEkf~XeIm>vNOrIOZ zF2OJ4_ADo;alwM=y)!XgR};*;JEgP`W(E2|b4)%|>>aXU?`&e1|LHIjl;tnRo%x6Ip=;7noo3N!5PyE8g%_)`)s&vmXZXHRvfxhNH7nK>)C z;|k5JmOj@i?ft4OSN1=%yL8JbY_Hi?kRB&f4y!M z7P2I@ee=@i8U^6xXxBz&>=NY|KA~D-D1o6ylHfb{MWMB5$1zg*M9USRp0LP0mY?`b z)TsE}U5%Wg8GJbaDF(%i*dc$B7DejI<(Yv-AU5^wuk7y?AHGj~ZFu?}QNcPy$1ZB*O19Q~8-H8Y%U*Z(e$t0NkTnW4u$6 z+2v3y8ZP@|1ijbprhn0I0JN(tep=!N-97{3I8`mITNM; zEsycjpou7^K>i~^53w`g+;UVt3FjW7CX*By>2+yv;dHLo){E6!OZ*0{V!`1q(M>wD|8y>=9b@! zau}Ltwc!Gc7!G4j>hjmY$%Vr~It3fxKd>z@f|8KA7El^88$@Eq0z#yQ!fKfW0JS|s zT>#&Upe7H}8(=U1s~~Nr^2|nn7#0BT4~7*O&rKu80&m@D392p<&Try9ad4^yRFmP^ zf%CEsXlexuZo^=5Wv4#aF)jvf!(g$HFVS>qnv^iu2vl&bX*!$Mcq9iwMxT)Hr_(5QP8X<}u#Dq*8 zX{x%22~eVA$DKM7sukhJAgL#sVM{ZJ@$345Y8GkIe2iFvv(#KSP=@ z(}zy`o0ODmY^DvLEN_$!DGBUuBaVg~u(p2D;qC#Y6%(y5Qcg~+&n}vKi+aia>*^OC z&L?*Iw*UdN>+2)KZOlOy@TD+?A%Z{$L*o+8qWeQ`1;v1TutJFf0m zMVbBdqVvedb^4MuJLazOGdl|7{`2qOXJh@m!#UKhzP`S%Z}aAfHlTrEP$G9v8Ew+g zIQ?}0{p0H1SHHT)xFxnwzVFvd8$bbAI3)@;y2|$*LWF_t@zjg+2cBa^6kr z&pDg}?MQ;%e?R>Yr-8$F2L$Gbzu7&sB>Ly>w@$7snAa%#!B0ND>qvk9$&Xe!KdG{S za@KxpAw*B8%-i&ZC#vUl6ej)`PPD;+pdqsVI$3_0wziLzYs1FDD>p1WOh>gYaOAcAFq2e$PE&0^o zLaGJme*ea(Hx6T6p-qix#K^8WNE&%6ZIIY?@F%HJp{L(|#XRCc$ z!tVDpgXhCVFrWOX+fS&>GYm@0b%X~7By!fD)|(%g>hJ%@+TmJ}0Izz*b=3=-`Lxbv zrb64p748FODM~_A1W;yU-Kr~;}A>1oW0+Y$(#Mf=r@4| zYs4}A?;{VO;IsBy%g9_N#=(U6=;@!84=*n|Xyve$Fy~0V+bIXe*A5+b$M{9$lRLwi ztL1{j-Mm4AO&BcK74PgXM#a#7_I|6QgHASeJ^Xf)e@e# za${@XeKS|f1&3Jx1~~yJ2YLs!>AnfEH?DqY*Lx4X_Q9!FJhDeiSZp^gyKj;WHqkq& zC5nPfN!az?1Fv~#`el#qakL|^ffK#@8p16~Mli2|PGNk_TXxNB9-4|e67m|b-^5T! z7GJaMa!CZpV7(B&2n(QlK9s|G5IY@8;gfJ6NXu&gi}|7DlBgnE7KMDUJ=oU00E~qo z(&VoI#O5^+$ZSC0QpB&F!^*ortzId=M{AMrz9pI;nq9(W057RBD(@PJa@)}tz?DF& zq)O)L3iB5kqw+4W`gDhfU!te4i2I9-U3pidE!Xsao&V0Te zwUxs@TpqcIK?veZ{D)TTlGZjD2SDm(S8X6SU-M&yf|~SOC=z2iwjN zZP!(pe>$^oZ#lE~q$H_J?~`TVA{eNtc{>1@-3|bk8pkW;PWDw4+}T;-SqNtd<+|$1 z#U6r>Zwl6J{AgofiW^DP2QT?z6c@@rB8{)FMfY&eLWf3 zThHu0DJ#et!X2F3G1>80$pJ8D>RgBWR^~dB@WG4U`@mG4j-1YS&svS9jC_*#@dBu> z^uDnLLQsI8aJ`;1sh zOFst;!48+YBgoO`wEy_f?(+(?i{n(gv%(Xor#+D@=t_+M$EddHVr$u~c^+sJr;E1h zO33y6<;r_5rePx;DhPh0pGfAl6M5{6?5o7YKomTfh2K>bUJojPjCMw}UeYFfqFA-q z0bUR4fSh(lcmZxd>44i0+e(|JX+b5G&(ha}Dj=twk**kGGxB>~lZV|10v_ttkm4bO z8X&KoF_Fx}J`dI85x7h$ZA3mhBU*i+J5lLS4uQ)L(#8>)?TlU>Wg4QK^moYOf@otD zneB{eGn4}jWe`U7X7seBw>w^O!A{P<)zJ~)>o}S1jFBwRhpsxCMlh`^0#^b*6W!$e zr*FIUeRsbUXtdBK#Q70&??UDIJ& ztxg%W>4NVwLW_>9Xf1z+vCo-HDyfXtu}TnnmCB&fg0|3W*Y>MdA+~6@MV50izsi7H zxggXk%iwsWnij&ei(mcVR2`vx7Fmg$xX3#9B;(p`^nWme!D@xUVQM~G2*;}SpU&*P zxB#Mo7Fl_O>4Cdw?A_=x*B)62UnKj}TR3CZL}<4~mh;rCo?#>@Hn@yiU}rR`Os%g+ zXtza{b6y!6$a*1RJoQonQTH@X_1u{=Qjs0t>-eK2Q0EFE))9C zB0C3O1pf#+$s!9{m$p&3XSDi+_}hTA*s(|Wre2p2Z%+<&4RwjQsmB%KI5xc>gH3V- z&5|QVA~Tdjou<`1M6}m&kaH0?^|(SD6Fk7jO>!KG1_x-kh4s=pgk4V;=OS+ESry{I z3vT=lG!8f5?X1=z!il@7XI6+4K^1f`V0M~T>k#LJZ|d>G00?Z7qY#!RMiJ%2+|+{# zaRg><3y>IyYAGxy>ZTs<=Lpy&M+U4;(`qKb>7=(NMLLwL@HwDI?xMtdmx_n<90a<6 zuHyi5W0!EX$i+^GA~+D!aBfW2!HyZ;DD(u8mhqq~fYa82c)|@QfUn18&5?piU56Q$4kt5s(JN1J9#_12GMaA}}QDxENqoIMfILqye_ma>LRSzzXca zDTRPE2oA(J`f(ui!wAle3ZhUPMwCcRUS~u>jRuS%hz5+wY>$m=gIo}MHax_XkE^$i<)IPcjAT~C+r z5BtL`e@8bU!lglj=e(I@q8CPby3l7~3v8q&kL?|n9*DAWBl+%35a3twL?8{0xls~heQ!7N0d$mfBd4DzL^nEo5-qYdaMM6Wt*1X zxZ>4|cTxJ_IxeoKp7vbgIVI4Zgfggq80=|=vQh_;;qkoy$x1G4XVe|6S(5>>X0r%8 zqwXL%$WTE||EH2)b@2$+WTB1XP=dCC z+~K;zL;ppf_P|`)A>CTmAHkwL63ZP4Qcb5mK!lw!k_Ewx+5@@qq{TIxm2r{qG^^G# zi&c9d?JT{P-*2)JEiBu0qA{oK49x~0LoBXA(j^Fut?6vu5s++@?9uKyX#LZkW+Zy* zx!5I0QP_cN!u1BiK48H%!hpPmu%19&0_p=6u@FHI*Au8W0EHMbY-b2mEuOw$ zz$Ei#yg!mA@hG^SK>aboIkM`*7Q+B6eG&!j=;;*v7R)B$GHz6d!0rPU>Jyf2TCko# zU4Z_%i^?GBVQ~$V!$EJ{nQz8yzVT8F^A$!~X!H7YLB2xadIM#uY0J3B%^nsSbm@znFah|3I5RmU8H~`xYW15bp!)=R!8KV#HA>f(5SCdauRp1(f z?YPu*ygFily6B6rV~kd^0D`d9pxW*gJ0XC9Kw5$N%P5R~?P@o)x=tZ4h8Tze7h`x0 zQO%7arrtnUkSJjU^ims*7&O@LbxRZn(^i9OZN5S=^#-DXL}|O2VBNWBjnI8OZJO>x zxD`>dB2#(TYEXTUuaGl4C9V(h70QHO$X6%}|N4@z@Dk2R5)p~~H=u^4nF!k%^$a5H zjJgTjIvCSqCC(E@Gw;BjKu|!gLrds~;LteY=-rX_xG>zdP(h+}BTd|55epgW2?QmQ z1<&^deh3b&^WyE$iEbwhEEY4AGrSp%IiuJKY=AXD0Ox6k@k4NE;z+z5Ix$|c6SyGJ zNR8iTTZ!KgMST$fSRAN;e+Uk3434)GC$gO|*yDDw!-FK@Zq>*kn4Z87!J&Qdc${-C zww*8*hxRfzSUgR_SztS)zz@NpQHT;zcE(5+7a$69L^HsX#e{wc4vk|Mz$T%L{<({a zHzSGbsXOya$s>@>0aZeV6R(aO?EpUV@>od`EFV)Q(he}aX%RaD64ttaWu|#0xc~wR zA=OG6bDVSVdryI8fYK~puq07-$AnFbryZCD#ejYOvoN;BIc!rXsCOv_`wNKr6`>`7 z2IEuE?>&W}9;;)**%(J%+4E@aM&!x!e$?kb2*@LiS`wOQu{g3$;(kSF3Y^UVnT2`l*8v60W9r_lBREhxQvT| zFFycK$AlS1Msi@F->=LI!fkK}6@>OHLQ`O7*oCmpvo86-12&vknBYJt2U`-# zhS9GGJ$1kNAE%iMnj!xonz?*iuyIrAM}soy^{xv(9C!a(F^s$5Z3|Pn`169x&d>cE zRcCR*Mhc+1fb%P)Fqc2a4nCxM1&Djb4uX_bUp@jKfQKJmw1~!Ia&YhG)dzpHoTS{l zep)NZz3Yv&;qbw|PfU&FwXg#ac|WYC(|v`#H?wAI(KI}m&*?vC82j$7x&IRmXV=42 zhWZ`+=aYiVsBWqS>a8bQyo;a7be&Ms2dk@l8G3a>O&V7)0Qz@Y+3Er|nUu;k-c-xx zJKB8*vZMa5jAYr;)r`MQwX97xyPl-3MRlMnZgIiJ^B|c!L256)s;PGIRlVVc z-td-!%QjVR*;iRWWvc1BF8J9DH#DxGdWEwVh3HHdM~Ld)aA#93fgUUc_ysCAs1JVz zzYQe(XMxCN;qcGEWehCFe<2&;Sa#7g1WIIkSt?aGu7KNoc0Jlci56r%_9C_Ex&(R= zr8{W=&_vJ!T5Z|(ES1$tb!UD6ZW}HlEg5M7Q0VAEkPP{&h zMyQr!-(5bo7j&(XB^vcoy~f=S_1?wL;0)Yp!6mT>@W9ZxLV$3#@=GD$po;efBCoW- z9voJ#2!Vzw&iN2XXzZ%R{C3Z}8)TwheQ2n*!c`1@4!!GcsKRtpPJmBA;GSVrIrwSx zNFSUluA_7-jSjLy8b2wVnE`m zNdLFd|G~Dwf04?b6vN@Lbm9<0iCh4y&xClh>RDvJv)#x0zn%W0+J*0@!c!x1SY(^y zD_6HFmUCg{iJ*cI$A6c~A(Z)@AD}1)_pQt*mA2N*+LK^5s2;yUg*ZO=-R(a9DSCd8 ziVSpaSet2WQzTAX*Y>p=J_9QGKE$23@*ks52DWWjyS=Mz0Vs~BVNlM7Q{i)PAgH6f zt3B&!?Y`e)_TRUA9qH0?$5x7AM3qPPMNl6ugD=1*;Ar?T>;oT!D`&vqd*K`3cn_$u zkmMR1ymBOam)-m5gW>v%pqowL1z`|YpAPqR7Q>NnFdPW`!@l4JRhOFEorkV{p!2@a zYJ!2_oGXPWq3uG*ti0pV=8wR!a1J9;wmb$wC{@S|#t=`o9=p8FFU2TM@ z(g0tO(d8$@qo0N?ABT^@rcDnV52`H>Y}&N!&Mke9)-EUGZH^L&!YjG0p;I7U3N73E z`Z`ry`ueuDEQ&7;ZG~5HQ6<44QO9Wuwr0Z1PlG#ZYwrURS7EsiNNw#M-&`KfvjZ%cefG6C~z>k+uClrDHsf9 uRb7I?;7vERwRIaxbevP*U^pbY21s|eV?Y-LPLV^@z~ZR37+9iG9R~m@1k1Sq literal 0 HcmV?d00001