documentation for named server UI

docs/source/changelog.md

@@ -20,8 +20,10 @@ whether it was through discussion, testing, documentation, or development.
 - Support TLS encryption and authentication of all internal communication.
   Spawners must implement `.move_certs` method to make certificates available
   to the notebook server if it is not local to the Hub.
-- There is now full UI support for managing named servers (TODO: screenshot).
+- There is now full UI support for managing named servers.
   With named servers, each jupyterhub user may have access to more than one named server. For example, a professor may access a server named `research` and another named `teaching`.
+
+  ![named servers on the home page](./images/named-servers-home.png)
 - Authenticators can now expire and refresh authentication data by implementing
   `Authenticator.refresh_user(user)`.
   This allows things like OAuth data and access tokens to be refreshed.

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

@@ -145,3 +145,37 @@ 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, so they are
 difficult for admins to update later.
+
+## Named servers
+
+By default, in a JupyterHub deployment each user has exactly one server.
+
+JupyterHub can, however, have multiple servers per user.
+This is most 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 one server.
+
+To allow named servers:
+
+```python
+c.JupyterHub.allow_named_servers = True
+```
+
+Named servers were implemented in the REST API in JupyterHub 0.8,
+and JupyterHub 1.0 introduces UI for managing named servers via the user home page:
+
+![named servers on the home page](../images/named-servers-home.png)
+
+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.
+
+The number of named servers per user can be limited by setting
+
+```python
+c.JupyterHub.named_server_limit_per_user = 5
+```

docs/source/reference/rest.md

@@ -158,11 +158,6 @@ The same servers can be stopped by substituting `DELETE` for `POST` above.
 
 ### Some caveats for using named-servers
 
-The named-server capabilities are not fully implemented for JupyterHub as yet.
-While it's possible to start/stop a server via the API, the UI on the 
-JupyterHub control-panel has not been implemented, and so it may not be obvious
-to those viewing the panel that a named-server may be running for a given user.
-
 For named-servers via the API to work, the spawner used to spawn these servers
 will need to be able to handle the case of multiple servers per user and ensure
 uniqueness of names, particularly if servers are spawned via docker containers