Repository: jupyterhub/jupyterhub

Issue:
FAQ audience confusion
This FAQ item is unfortunately causing some local support problems for our institution:

https://github.com/jupyterhub/jupyterhub/blob/38ba275367936c9a5a081a7b5acf326134705a0a/docs/source/faq/faq.md?plain=1#L3

As I understand, this FAQ item is written for a sophisticated end-user who is setting up their own jupterhub on their own servers. They have sysadmin access to the filesystems to configure it so that users on their system can easily share notebooks using these instructions, e.g. with [Jupyterlab "copy shareable link"](https://jupyterlab.readthedocs.io/en/stable/user/files.html).

However, these instructions cause support problems downstream when our faculty assume they can use these instructions to allow their students to share links to their notebooks. Of course, this depends on how the institution's jupyterhub is configured on the backend.

If you could clarify this FAQ item for these audiences, I think that would help reduce frustration for general end users who search google for how to share a notebook link and stumble onto this entry. I think what most of them are searching for is [RTC (Real Time Collaboration) link sharing](https://jupyterlab.readthedocs.io/en/stable/user/rtc.html) which (as of March 2023) is not yet ready for prime-time and depends on the jupyterhub server environment configured for it, which most are not. Sometimes what they are trying to do can be accomplished with [nbgitpuller link generator](https://hub.jupyter.org/nbgitpuller/link), but I think most people are looking for RTC.

Thanks!


Discussion:
Thank you for opening your first issue in this project! Engagement like this is essential for open source projects! :hugs:
<br>If you haven't done so already, check out [Jupyter's Code of Conduct](https://github.com/jupyter/governance/blob/master/conduct/code_of_conduct.md). Also, please try to follow the issue template as it helps other other community members to contribute more effectively.
![welcome](https://raw.githubusercontent.com/jupyterhub/.github/master/images/welcome.jpg)
You can meet the other [Jovyans](https://jupyter.readthedocs.io/en/latest/community/content-community.html?highlight=jovyan#what-is-a-jovyan) by joining our [Discourse forum](http://discourse.jupyter.org/). There is also an intro thread there where you can stop by and say Hi! :wave:
<br>Welcome to the Jupyter community! :tada:

The original question they submitted to our consultants was this:

> I made an RMD file to share with my students but do not know how to make a shareable link- there is no 'share' option on the menu

I just met with the faculty, and In the end it seems all they needed was nbgitpuller, so suggesting end users start there would help.
Yeah! It's not obvious. Part of why it's confusing is that 'share' can mean several things in a JupyterHub context, but there are 3 primary answers:

1. share a link to this file on the visitor's own server, assuming either shared or sufficiently similar filesystem (JupyterLab's 'copy shareable link' does this)
2. share a link to this file on this server, assuming (or granting) access (the RTC case). [jupyterlab-link-share](https://github.com/jupyterlab-contrib/jupyterlab-link-share) provides this, and it's really `https://current-url/lab/tree/...` (note: _granting_ access to a user's JupyterHub server via the extension is very likely not advisable, but JupyterHub 3.0 permissions allows admin control of permissions)
3. share a _download_ link from an external/canonical source, like a git repo. nbgitpuller provides these links, but not a way to generate them from the editing view in jupyterlab, as far as I know.

The FAQ only describes case number 1, so we can update it to cover the other two as well.

Resolving patch:
diff --git a/docs/source/conf.py b/docs/source/conf.py
--- a/docs/source/conf.py
+++ b/docs/source/conf.py
@@ -201,6 +201,7 @@ def setup(app):
     "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 -------------------------------------


Test patch: