Merge branch 'main' into alexanderchosen

docs/source/reference/config-ghoauth.md

@@ -5,15 +5,15 @@ deployment with the following assumptions:
 
 - Running JupyterHub on a single cloud server
 - Using SSL on the standard HTTPS port 443
-- Using GitHub OAuth (using oauthenticator) for login
+- Using GitHub OAuth (using [OAuthenticator](https://oauthenticator.readthedocs.io/en/latest)) for login
 - Using the default spawner (to configure other spawners, uncomment and edit
   `spawner_class` as well as follow the instructions for your desired spawner)
 - Users exist locally on the server
 - Users' notebooks to be served from `~/assignments` to allow users to browse
   for notebooks within other users' home directories
 - You want the landing page for each user to be a `Welcome.ipynb` notebook in
-  their assignments directory.
-- All runtime files are put into `/srv/jupyterhub` and log files in `/var/log`.
+  their assignments directory
+- All runtime files are put into `/srv/jupyterhub` and log files in `/var/log`
 
 The `jupyterhub_config.py` file would have these settings:
 
@@ -69,7 +69,7 @@ c.Spawner.args = ['--NotebookApp.default_url=/notebooks/Welcome.ipynb']
 ```
 
 Using the GitHub Authenticator requires a few additional
-environment variable to be set prior to launching JupyterHub:
+environment variables to be set prior to launching JupyterHub:
 
 ```bash
 export GITHUB_CLIENT_ID=github_id
@@ -79,3 +79,5 @@ export CONFIGPROXY_AUTH_TOKEN=super-secret
 # append log output to log file /var/log/jupyterhub.log
 jupyterhub -f /etc/jupyterhub/jupyterhub_config.py &>> /var/log/jupyterhub.log
 ```
+
+Visit the [Github OAuthenticator reference](https://oauthenticator.readthedocs.io/en/latest/api/gen/oauthenticator.github.html) to see the full list of options for configuring Github OAuth with JupyterHub.

docs/source/reference/config-user-env.md

@@ -4,23 +4,31 @@ To deploy JupyterHub means you are providing Jupyter notebook environments for
 multiple users. Often, this includes a desire to configure the user
 environment in a custom way.
 
-Since the `jupyterhub-singleuser` server extends the standard Jupyter notebook server, most configuration and documentation that applies to Jupyter Notebook applies to the single-user environments. 
-Configuration of user environments typically does not occur through JupyterHub itself, but rather through system-wide Jupyter's configuration, which is inherited by `jupyterhub-singleuser`.
+Since the `jupyterhub-singleuser` server extends the standard Jupyter notebook
+server, most configuration and documentation that applies to Jupyter Notebook
+applies to the single-user environments. Configuration of user environments
+typically does not occur through JupyterHub itself, but rather through the system-wide
+configuration of Jupyter, which is inherited by `jupyterhub-singleuser`.
 
 **Tip:** When searching for configuration tips for JupyterHub user environments, you might want to remove JupyterHub from your search because there are a lot more people out there configuring Jupyter than JupyterHub and the configuration is the same.
 
 This section will focus on user environments, which includes the following:
 
-- Installing packages
-- Configuring Jupyter and IPython
-- Installing kernelspecs
-- Using containers vs. multi-user hosts
+- [Installing packages](#installing-packages)
+- [Configuring Jupyter and IPython](#configuring-jupyter-and-ipython)
+- [Installing kernelspecs](#installing-kernelspecs)
+- [Using containers vs. multi-user hosts](#multi-user-hosts-vs-containers)
 
 ## Installing packages
 
 To make packages available to users, you will typically install packages system-wide or in a shared environment.
 
-This installation location should always be in the same environment where `jupyterhub-singleuser` itself is installed, and must be _readable and executable_ by your users. If you want users to be able to install additional packages, it must also be _writable_ by your users.
+
+This installation location should always be in the same environment where
+`jupyterhub-singleuser` itself is installed in, and must be _readable and
+executable_ by your users. If you want your users to be able to install additional
+packages, the installation location must also be _writable_ by your users.
+
 
 If you are using a standard Python installation on your system, use the following command:
 
@@ -84,7 +92,11 @@ c.MappingKernelManager.cull_interval = 2 * 60
 You may have multiple Jupyter kernels installed and want to make sure that they are available to all of your users. This means installing kernelspecs either system-wide (e.g. in /usr/local/) or in the `sys.prefix` of JupyterHub
 itself.
 
-Jupyter kernelspec installation is system wide by default, but some kernels may default to installing kernelspecs in your home directory. These will need to be moved system-wide to ensure that they are accessible.
+
+Jupyter kernelspec installation is system-wide by default, but some kernels
+may default to installing kernelspecs in your home directory. These will need
+to be moved system-wide to ensure that they are accessible.
+
 
 To see where your kernelspecs are, you can use the following command:
 
@@ -115,19 +127,22 @@ depending on what Spawner you are using.
 The first category is a **shared system (multi-user host)** where
 each user has a JupyterHub account, a home directory as well as being
 a real system user. In this example, shared configuration and installation
-must be in a 'system-wide' location, such as `/etc/` or `/usr/local`
+must be in a 'system-wide' location, such as `/etc/`, or `/usr/local`
 or a custom prefix such as `/opt/conda`.
 
 When JupyterHub uses **container-based** Spawners (e.g. KubeSpawner or
 DockerSpawner), the 'system-wide' environment is really the container image used for users.
 
+
 In both cases, you want to _avoid putting configuration in user home
 directories_ because users can change those configuration settings. Also, home directories typically persist once they are created, thereby making it difficult for admins to update later.
 
 ## Named servers
 
+
 By default, in a JupyterHub deployment, each user has one server only.
 
+
 JupyterHub can, however, have multiple servers per user.
 This is mostly useful in deployments where users can configure the environment in which their server will start (e.g. resource requests on an HPC cluster), so that a given user can have multiple configurations running at the same time, without having to stop and restart their own server.
 
@@ -146,7 +161,10 @@ as well as the admin page:
 
 ![named servers on the admin page](../images/named-servers-admin.png)
 
-Named servers can be accessed, created, started, stopped, and deleted from these pages. Activity tracking is now per-server as well.
+
+Named servers can be accessed, created, started, stopped, and deleted
+from these pages. Activity tracking is now per server as well.
+
 
 To limit the number of **named server** per user by setting a constant value, use this:
 
@@ -172,9 +190,12 @@ If `named_server_limit_per_user` is set to `0`, no limit is enforced.
 
 (classic-notebook-ui)=
 
-## Switching back to classic notebook
+## Switching back to the classic notebook
+
+
+By default, the single-user server launches JupyterLab,
+which is based on [Jupyter Server][].
 
-By default, the single-user server launches JupyterLab, which is based on [Jupyter Server][].
 This is the default server when running JupyterHub ≥ 2.0.
 To switch to using the legacy Jupyter Notebook server, you can set the `JUPYTERHUB_SINGLEUSER_APP` environment variable
 (in the single-user environment) to:
@@ -187,8 +208,13 @@ export JUPYTERHUB_SINGLEUSER_APP='notebook.notebookapp.NotebookApp'
 [jupyter notebook]: https://jupyter-notebook.readthedocs.io
 
 :::{versionchanged} 2.0
-JupyterLab is now the default singleuser UI, if available,
-which is based on the [Jupyter Server][], no longer the legacy [Jupyter Notebook][] server.JupyterHub prior to 2.0 launched the legacy notebook server (`jupyter notebook`),and Jupyter server could be selected by specifying the following:
+
+JupyterLab is now the default single-user UI, if available,
+which is based on the [Jupyter Server][],
+no longer the legacy [Jupyter Notebook][] server.
+JupyterHub prior to 2.0 launched the legacy notebook server (`jupyter notebook`),
+and the Jupyter server could be selected by specifying the following:
+
 
 ```python
 # jupyterhub_config.py

docs/source/reference/spawners.md

@@ -267,8 +267,8 @@ Spawners mainly do one thing: launch a command in an environment.
 
 The command-line is constructed from user configuration:
 
-- Spawner.cmd (default: `['jupterhub-singleuser']`)
-- Spawner.args (cli args to pass to the cmd, default: empty)
+- Spawner.cmd (default: `['jupyterhub-singleuser']`)
+- Spawner.args (CLI args to pass to the cmd, default: empty)
 
 where the configuration:
 
@@ -319,12 +319,12 @@ Optional environment variables, depending on configuration:
 - JUPYTERHUB_ROOT_DIR - the root directory of the server (notebook directory), when Spawner.notebook_dir is defined (new in 2.0)
 - JUPYTERHUB_DEFAULT_URL - the default URL for the server (for redirects from /user/:name/),
   if Spawner.default_url is defined
-  (new in 2.0, previously passed via cli)
+  (new in 2.0, previously passed via CLI)
 - JUPYTERHUB_DEBUG=1 - generic debug flag, sets maximum log level when Spawner.debug is True
-  (new in 2.0, previously passed via cli)
+  (new in 2.0, previously passed via CLI)
 - JUPYTERHUB_DISABLE_USER_CONFIG=1 - disable loading user config,
   sets maximum log level when Spawner.debug is True (new in 2.0,
-  previously passed via cli)
+  previously passed via CLI)
 
 - JUPYTERHUB*[MEM|CPU]*[LIMIT_GUARANTEE] - the values of cpu and memory limits and guarantees.
   These are not expected to be enforced by the process,

docs/source/reference/websecurity.md

@@ -5,7 +5,7 @@ The **Security Overview** section helps you learn about:
 - the design of JupyterHub with respect to web security
 - the semi-trusted user
 - the available mitigations to protect untrusted users from each other
-- the value of periodic security audits.
+- the value of periodic security audits
 
 This overview also helps you obtain a deeper understanding of how JupyterHub
 works.
@@ -32,7 +32,7 @@ servers) as a single website (i.e. single domain).
 
 To protect users from each other, a user must **never** be able to write arbitrary
 HTML and serve it to another user on the Hub's domain. JupyterHub's
-authentication setup prevents a user writing arbitrary HTML and serving it to
+authentication setup prevents a user from writing arbitrary HTML and serving it to
 another user because only the owner of a given single-user notebook server is
 allowed to view user-authored pages served by the given single-user notebook
 server.
@@ -101,8 +101,8 @@ pose additional risk to the web application's security.
 
 ### Encrypt internal connections with SSL/TLS
 
-By default, all communication on the server, between the proxy, hub, and single
--user notebooks is performed unencrypted. Setting the `internal_ssl` flag in
+By default, all communications on the server, between the proxy, hub, and single
+-user notebooks are performed unencrypted. Setting the `internal_ssl` flag in
 `jupyterhub_config.py` secures the aforementioned routes. Turning this
 feature on does require that the enabled `Spawner` can use the certificates
 generated by the `Hub` (the default `LocalProcessSpawner` can, for instance).
@@ -118,7 +118,7 @@ extend to securing the `tcp` sockets as well.
 
 ## Security audits
 
-We recommend that you do periodic reviews of your deployment's security. It's
+We recommend that you do periodic reviews of your deployment's security. It is
 good practice to keep JupyterHub, configurable-http-proxy, and nodejs
 versions up to date.
 
@@ -129,7 +129,7 @@ A handy website for testing your deployment is
 
 ## Vulnerability reporting
 
-If you believe you’ve found a security vulnerability in JupyterHub, or any
+If you believe you have found a security vulnerability in JupyterHub, or any
 Jupyter project, please report it to
 [security@ipython.org](mailto:security@ipython.org). If you prefer to encrypt
 your security reports, you can use [this PGP public