Resolved items as guided by @minrk comments

docs/source/explanation/index.md

@@ -2,29 +2,17 @@
 
 _Explanation_ documentation provide big-picture descriptions of how JupyterHub works. This section is meant to build your understanding of particular topics.
 
-## Administration
-
-This section provides information relevant to running your own JupyterHub over time.
 
 ```{toctree}
 :maxdepth: 1
 
-admin/capacity-planning
+capacity-planning
-admin/database
+database
-admin/websecurity
+websecurity
-admin/oauth
+oauth
+../rbac/index
 ```
-
-## JupyterHub RBAC
-
-This section covers how Role Based Access Control (RBAC) is implemented in JupyterHub to control access to Jupyterhub's API resources.
-
 <!---
 The JupyterHub RBAC source files are contained in the source/rbac folder
 --->
 
-```{toctree}
-:maxdepth: 2
-
-../rbac/index
-```

docs/source/howto/index.md

@@ -14,6 +14,7 @@ separate-proxy
 templates
 upgrading
 log-messages
+
 ```
 
 (config-examples)=

docs/source/redirects.txt

@@ -8,7 +8,7 @@
 "admin/log-messages.md" "howto/log-messages.md"
 "reference/proxy.md" "howto/proxy.md"
 "reference/templates.md" "howto/templates.md"
-"quickstart-docker.md" "tutorial/installation/quickstart-docker.md"
+"quickstart-docker.md" "tutorial/quickstart-docker.md"
 "reference/config-examples.md" "howto/index.md"
 "getting-started/institutional-faq.md" "faq/institutional-faq.md"
 "troubleshooting.md" "faq/troubleshooting.md"
@@ -17,5 +17,5 @@
 "reference/rest.md" "howto/rest.md"
 "reference/separate-proxy.md" "howto/separate-proxy.md"
 "admin/upgrading.md" "howto/upgrading.md"
-"installation-basics.md" "tutorial/installation/installation-basics.md"
+"installation-basics.md" "tutorial/installation-basics.md"
-"quickstart.md" "tutorial/installation/quickstart.md"
+"quickstart.md" "tutorial/quickstart.md"

docs/source/reference/event-logging.md

@@ -1,7 +1,3 @@
-<!---
-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/reference/index.md

@@ -12,117 +12,27 @@ This section is divided into two broad subsections:
 
 ## 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.
-
-### Technical overview
-
-Provides an overview of JupyterHub's components and how they work.
-
 ```{toctree}
 :maxdepth: 1
 
-technical-reference/technical-overview
+technical-overview
-```
+authenticators
-
+spawners
-### Subsystems
+config-reference
-
+services
-Find details about the different JupyterHub subsystems.
+urls
-
+event-logging
-```{toctree}
+monitoring
-:maxdepth: 1
+gallery-jhub-deployments
-
+changelog
-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
+reference-api/index.md
-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/reference-api/index.md

@@ -0,0 +1,36 @@
+(api-index)=
+
+# JupyterHub 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
+app
+auth
+spawner
+proxy
+user
+service
+services.auth
+```
+
+[openapi initiative]: https://www.openapis.org/
+

docs/source/reference/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} ../../../../../../jupyterhub/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} ../../../../../../jupyterhub/examples/service-whoami-flask/whoami-flask.py
+```{literalinclude} ../../../../jupyterhub/examples/service-whoami-flask/whoami-flask.py
 :language: python
 ```
 

docs/source/tutorial/index.md

@@ -11,9 +11,9 @@ running on your own infrastructure.
 ```{toctree}
 :maxdepth: 1
 
-installation/quickstart
+quickstart
-installation/installation-basics
+installation-basics
-installation/quickstart-docker
+quickstart-docker
 ```
 
 ## Getting Started
@@ -41,5 +41,5 @@ JupyterHub's functionalities can be accessed using its API. In this section, we
 ```{toctree}
 :maxdepth: 1
 
-api/server-api
+server-api
 ```

docs/source/tutorial/server-api.md

@@ -252,7 +252,7 @@ data: {"progress": 100, "ready": true, "message": "Server ready at /user/test-us
 
 Here is a Python example for consuming an event stream:
 
-```{literalinclude} ../../../../examples/server-api/start-stop-server.py
+```{literalinclude} ../../../examples/server-api/start-stop-server.py
 :language: python
 :pyobject: event_stream
 ```
@@ -285,7 +285,7 @@ The only way to wait for a server to stop is to poll it and wait for the server
 
 This Python code snippet can be used to stop a server and the wait for the process to complete:
 
-```{literalinclude} ../../../../examples/server-api/start-stop-server.py
+```{literalinclude} ../../../examples/server-api/start-stop-server.py
 :language: python
 :pyobject: stop_server
 ```
@@ -325,7 +325,7 @@ In summary, the processes involved in managing servers on behalf of users are:
 The example below demonstrates starting and stopping servers via the JupyterHub API,
 including waiting for them to start via the progress API and waiting for them to stop by polling the user model.
 
-```{literalinclude} ../../../../examples/server-api/start-stop-server.py
+```{literalinclude} ../../../examples/server-api/start-stop-server.py
 :language: python
 :start-at: def event_stream
 :end-before: def main