Restructured references section of the docs

docs/source/api/index.md

@@ -1,37 +0,0 @@
-(api-index)=
-
-# JupyterHub API
-
-<!--
-    Below is a MyST field list, using MyST substitution, as supported
-    by enabling the respective MyST extensions in docs/source/conf.py.
--->
-
-:Date: {{ date }}
-:Release: {{ version }}
-
-JupyterHub also provides a REST API for administration of the Hub and users.
-The documentation on [Using JupyterHub's REST API](using-jupyterhub-rest-api) provides
-information on:
-
-- what you can do with the API
-- creating an API token
-- adding API tokens to the config files
-- making an API request programmatically using the requests library
-- learning more about JupyterHub's API
-
-JupyterHub API Reference:
-
-```{toctree}
-:maxdepth: 3
-
-app
-auth
-spawner
-proxy
-user
-service
-services.auth
-```
-
-[openapi initiative]: https://www.openapis.org/

docs/source/events/index.md

@@ -1,3 +1,7 @@
+<!---
+This doc is part of the Technical references section of the References documentation.  
+--->
+
 # Event logging and telemetry
 
 JupyterHub can be configured to record structured events from a running server using Jupyter's [Telemetry System]. The types of events that JupyterHub emits are defined by [JSON schemas] listed at the bottom of this [page].

docs/source/howto/rest.md

@@ -57,7 +57,7 @@ jupyterhub token <username>
 This command generates a random string to use as a token and registers
 it for the given user with the Hub's database.
 
-In [version 0.8.0](../changelog.md), a token request page for
+In [version 0.8.0](changelog), a token request page for
 generating an API token is available from the JupyterHub user interface:
 
 :::{figure-md}
@@ -276,7 +276,7 @@ Pagination is enabled on the `GET /users`, `GET /groups`, and `GET /proxy` REST
 
 ## Enabling users to spawn multiple named-servers via the API
 
-Support for multiple servers per user was introduced in JupyterHub [version 0.8.](../changelog.md)
+Support for multiple servers per user was introduced in JupyterHub [version 0.8.](changelog)
 Prior to that, each user could only launch a single default server via the API
 like this:
 

docs/source/howto/upgrading.md

@@ -16,7 +16,7 @@ The steps are discussed in detail, so if you get stuck at any step you can alway
 
 ## Read the Changelog
 
-The [changelog](../changelog.md) contains information on what has
+The [changelog](changelog) contains information on what has
 changed with the new JupyterHub release and any deprecation warnings.
 Read these notes to familiarize yourself with the coming changes. There
 might be new releases of the authenticators & spawners you use, so

docs/source/index-about.md

@@ -9,6 +9,4 @@ about our community, as well as ways that you can connect and get involved.
 :maxdepth: 1
 
 contributor-list
-changelog
-gallery-jhub-deployments
 ```

docs/source/index.md

@@ -81,22 +81,6 @@ Today, you can find two main use cases:
 _It is important to evaluate these distributions before you can continue with the
 configuration of JupyterHub_.
 
-### Technical Reference
-
-```{toctree}
-:maxdepth: 2
-
-reference/index
-```
-
-### API Reference
-
-```{toctree}
-:maxdepth: 2
-
-api/index
-```
-
 ### Contributing
 
 We welcome you to contribute to JupyterHub in ways that are most exciting

docs/source/reference/index.md

@@ -1,20 +1,116 @@
 (reference-index)=
 
-# Technical Reference
+# Reference
+_Reference_ documentation provide technical descriptions about JupyterHub and how it works. 
+This section is divided into two broad subsections: 
+1. Technical reference.
+2. API reference.  
+---
+## Technical reference
 
 This section covers more of the details of the JupyterHub architecture, as well as
 what happens under-the-hood when you deploy and configure your JupyterHub.
 
-```{toctree}
-:maxdepth: 2
+### Technical overview
+Provides an overview of JupyterHub's components and how they work. 
 
-technical-overview
-urls
-authenticators
-spawners
-services
-rest-api
-monitoring
-../events/index
-config-reference
+```{toctree}
+:maxdepth: 1
+
+technical-reference/technical-overview
 ```
+
+### Subsystems
+
+Find details about the different JupyterHub subsystems. 
+```{toctree}
+:maxdepth: 1
+
+technical-reference/subsystems/authenticators
+technical-reference/subsystems/spawners
+```
+
+### Configuration
+
+Find useful information about configuring JupyterHub. 
+```{toctree}
+:maxdepth: 1
+
+technical-reference/configuration/config-reference
+technical-reference/configuration/services
+technical-reference/configuration/urls
+```
+
+### Events
+
+Find details about JupyterHub events and how to log them. 
+```{toctree}
+:maxdepth: 1
+
+../events/index
+```
+
+### Monitoring
+
+Find details about monitoring your JupyterHub deployment. 
+```{toctree}
+:maxdepth: 1
+
+technical-reference/monitoring/monitoring
+```
+
+### Deployments
+
+Find details about the institutions presently using JupyterHub. 
+```{toctree}
+:maxdepth: 1
+
+technical-reference/deployments/gallery-jhub-deployments
+```
+
+### Changelog
+
+Find details about changes to JupyterHub and its various releases.
+
+```{toctree}
+:maxdepth: 1
+
+technical-reference/changelog/changelog
+```
+---
+(api-index)=
+
+## API reference
+
+<!--
+    Below is a MyST field list, using MyST substitution, as supported
+    by enabling the respective MyST extensions in docs/source/conf.py.
+-->
+
+:Date: {{ date }}
+:Release: {{ version }}
+
+JupyterHub also provides a REST API for administration of the Hub and users.
+The documentation on [Using JupyterHub's REST API](using-jupyterhub-rest-api) provides
+information on:
+
+- what you can do with the API
+- creating an API token
+- adding API tokens to the config files
+- making an API request programmatically using the requests library
+- learning more about JupyterHub's API
+
+```{toctree}
+:maxdepth: 1
+
+rest-api
+api-reference/app
+api-reference/auth
+api-reference/spawner
+api-reference/proxy
+api-reference/user
+api-reference/service
+api-reference/services.auth
+```
+
+[openapi initiative]: https://www.openapis.org/

docs/source/reference/rest-api.md

@@ -1,3 +1,6 @@
+<!---
+This doc is part of the API references section of the References documentation.  
+--->
 (jupyterhub-rest-API)=
 
 # JupyterHub REST API

docs/source/reference/technical-reference/changelog/changelog.md

@@ -581,10 +581,10 @@ default 'user' role as expected.
 
 JupyterHub 2.0 is a big release!
 
-The most significant change is the addition of [roles and scopes][rbac]
+The most significant change is the addition of [roles and scopes](rbac)
 to the JupyterHub permissions model,
 allowing more fine-grained access control.
-Read more about it [in the docs][rbac].
+Read more about it [in the docs](rbac).
 
 In particular, the 'admin' level of permissions should not be needed anymore,
 and you can now grant users and services only the permissions they need, not more.

docs/source/reference/technical-reference/configuration/services.md

@@ -290,7 +290,7 @@ service. See the `service-whoami-flask` example in the
 [JupyterHub GitHub repo](https://github.com/jupyterhub/jupyterhub/tree/HEAD/examples/service-whoami-flask)
 for more details.
 
-```{literalinclude} ../../../examples/service-whoami-flask/whoami-flask.py
+```{literalinclude} ../../../../../../jupyterhub/examples/service-whoami-flask/whoami-flask.py
 :language: python
 ```
 
@@ -352,7 +352,7 @@ You will only get to this stage if the user has the required `access:services!se
 To retrieve the user model for the token, make a request to `GET /hub/api/user` with the token in the Authorization header.
 For example, using flask:
 
-```{literalinclude} ../../../examples/service-whoami-flask/whoami-flask.py
+```{literalinclude} ../../../../../../jupyterhub/examples/service-whoami-flask/whoami-flask.py
 :language: python
 ```
 

docs/source/reference/technical-reference/configuration/urls.md

@@ -53,7 +53,7 @@ c.JupyterHub.default_url = '/services/my-landing-service'
 
 ## `/hub/home`
 
-![The Hub home page with named servers enabled](../images/named-servers-home.png)
+![The Hub home page with named servers enabled](/images/named-servers-home.png)
 
 By default, the Hub home page has just one or two buttons
 for starting and stopping the user's server.
@@ -70,14 +70,14 @@ If you have a form-based username+password login,
 such as the default [PAMAuthenticator](https://en.wikipedia.org/wiki/Pluggable_authentication_module),
 this page will render the login form.
 
-![A login form](../images/login-form.png)
+![A login form](/images/login-form.png)
 
 If login is handled by an external service,
 e.g. with OAuth, this page will have a button,
 declaring "Log in with ..." which users can click
 to log in with the chosen service.
 
-![A login redirect button](../images/login-button.png)
+![A login redirect button](/images/login-button.png)
 
 If you want to skip the user interaction and initiate login
 via the button, you can set:
@@ -145,7 +145,7 @@ If something is really wrong, this can result in a redirect loop.
 Visiting this page will never result in triggering the spawn of servers
 without additional user action (i.e. clicking the link on the page).
 
-![Visiting a URL for a server that's not running](../images/not-running.png)
+![Visiting a URL for a server that's not running](/images/not-running.png)
 
 _Version changed: 1.0_
 
@@ -204,7 +204,7 @@ If `Spawner.options_form` is used,
 this will render a form,
 and a POST request will trigger the actual spawn and redirect.
 
-![The spawn form](../images/spawn-form.png)
+![The spawn form](/images/spawn-form.png)
 
 _Version added: 1.0_
 
@@ -218,7 +218,7 @@ which was responsible for triggering spawn and rendering progress, etc.
 
 ### `/hub/spawn-pending[/:username[/:servername]]`
 
-![The spawn pending page](../images/spawn-pending.png)
+![The spawn pending page](/images/spawn-pending.png)
 
 _Version added: 1.0_ this URL is new in JupyterHub 1.0.
 
@@ -236,7 +236,7 @@ and the page will show a link back to `/hub/spawn/...`.
 
 ## `/hub/token`
 
-![The token management page](../images/token-page.png)
+![The token management page](/images/token-page.png)
 
 On this page, users can manage their JupyterHub API tokens.
 They can revoke access and request new tokens for writing scripts
@@ -244,7 +244,7 @@ against the [JupyterHub REST API](using-jupyterhub-rest-api).
 
 ## `/hub/admin`
 
-![The admin panel](../images/named-servers-admin.png)
+![The admin panel](/images/named-servers-admin.png)
 
 Administrators can take various administrative actions from this page:
 

docs/source/reference/technical-reference/monitoring/monitoring.md

@@ -16,5 +16,5 @@ tool like [Grafana](https://grafana.com).
 ```{toctree}
 :maxdepth: 2
 
-metrics
+/reference/metrics
 ```

docs/source/reference/technical-reference/subsystems/authenticators.md

@@ -1,3 +1,5 @@
+(authenticators-reference)=
+
 # Authenticators
 
 The {class}`.Authenticator` is the mechanism for authorizing users to use the

docs/source/reference/technical-reference/subsystems/spawners.md

@@ -1,3 +1,5 @@
+(spawners-reference)=
+
 # Spawners
 
 A [Spawner][] starts each single-user notebook server.
@@ -175,7 +177,7 @@ This feature is enabled by setting `Spawner.options_form`, which is an HTML form
 inserted unmodified into the spawn form.
 If the `Spawner.options_form` is defined, when a user tries to start their server, they will be directed to a form page, like this:
 
-![spawn-form](../images/spawn-form.png)
+![spawn-form](/images/spawn-form.png)
 
 If `Spawner.options_form` is undefined, the user's server is spawned directly, and no spawn page is rendered.
 

docs/source/reference/technical-reference/technical-overview.md

@@ -18,7 +18,7 @@ Notebook server for each person in a group. Three subsystems are started
 by the `jupyterhub` command line program:
 
 - **Hub** (Python/Tornado): manages user accounts, authentication, and
-  coordinates Single User Notebook Servers using a [Spawner](./spawners.md).
+  coordinates Single User Notebook Servers using a [Spawner](spawners-reference).
 
 - **Proxy**: the public-facing part of JupyterHub that uses a dynamic proxy
   to route HTTP requests to the Hub and Single User Notebook Servers.
@@ -28,9 +28,9 @@ by the `jupyterhub` command line program:
 - **Single-User Notebook Server** (Python/Tornado): a dedicated,
   single-user, Jupyter Notebook server is started for each user on the system
   when the user logs in. The object that starts the single-user notebook
-  servers is called a **[Spawner](./spawners.md)**.
+  servers is called a **[Spawner](spawners-reference)**.
 
-![JupyterHub subsystems](../images/jhub-parts.png)
+![JupyterHub subsystems](/images/jhub-parts.png)
 
 ## How the Subsystems Interact
 
@@ -49,14 +49,14 @@ The proxy is the only process that listens on a public interface. The Hub sits
 behind the proxy at `/hub`. Single-user servers sit behind the proxy at
 `/user/[username]`.
 
-Different **[authenticators](./authenticators.md)** control access
+Different **[authenticators](authenticators-reference)** control access
 to JupyterHub. The default one [(PAM)](https://en.wikipedia.org/wiki/Pluggable_authentication_module) uses the user accounts on the server where
 JupyterHub is running. If you use this, you will need to create a user account
 on the system for each user on your team. However, using other authenticators you can
 allow users to sign in with e.g. a GitHub account, or with any single-sign-on
 system your organization has.
 
-Next, **[spawners](./spawners.md)** control how JupyterHub starts
+Next, **[spawners](spawners-reference)** control how JupyterHub starts
 the individual notebook server for each user. The default spawner will
 start a notebook server on the same machine running under their system username.
 The other main option is to start each server in a separate container, often using [Docker](https://jupyterhub-dockerspawner.readthedocs.io/en/latest/).
@@ -65,10 +65,10 @@ The other main option is to start each server in a separate container, often usi
 
 When a user accesses JupyterHub, the following events take place:
 
-- Login data is handed to the [Authenticator](./authenticators.md) instance for
+- Login data is handed to the [Authenticator](authenticators-reference) instance for
   validation
 - The Authenticator returns the username if the login information is valid
-- A single-user notebook server instance is [spawned](./spawners.md) for the
+- A single-user notebook server instance is [spawned](spawners-reference) for the
   logged-in user
 - When the single-user notebook server starts, the proxy is notified to forward
   requests made to `/user/[username]/*`, to the single-user notebook server.
@@ -121,9 +121,9 @@ all security and runtime files.
 
 There are two basic extension points for JupyterHub:
 
-- How users are authenticated by [Authenticators](./authenticators.md)
+- How users are authenticated by [Authenticators](authenticators-reference)
 - How user's single-user notebook server processes are started by
-  [Spawners](./spawners.md)
+  [Spawners](spawners-reference)
 
 Each is governed by a customizable class, and JupyterHub ships with basic
 defaults for each.