Moved first half of HowTo documentation

docs/source/api/index.md

@@ -11,7 +11,7 @@
 :Release: {{ version }}
 
 JupyterHub also provides a REST API for administration of the Hub and users.
-The documentation on [Using JupyterHub's REST API](../reference/rest.md) provides
+The documentation on [Using JupyterHub's REST API](rest-api) provides
 information on:
 
 - what you can do with the API

docs/source/changelog.md

@@ -581,7 +581,7 @@ and consider assigning only the necessary roles and scopes.
 [rbac]: ./rbac/index.md
 
 JupyterHub 2.0 requires an update to the database schema,
-so **make sure to [read the upgrade documentation and backup your database](admin/upgrading)
+so **make sure to [read the upgrade documentation and backup your database](upgrading-jupyterhub)
 before upgrading**.
 
 :::{admonition} stop all servers before upgrading

docs/source/getting-started/config-basics.md

@@ -99,4 +99,4 @@ maintenance, re-configuration, etc.), then user connections are not
 interrupted. For simplicity, by default the hub starts the proxy
 automatically, so if the hub restarts, the proxy restarts, and user
 connections are interrupted. It is easy to run the proxy separately,
-for information see [the separate proxy page](../reference/separate-proxy).
+for information see [the separate proxy page](separate-proxy).

docs/source/howto/index.md

@@ -3,6 +3,12 @@
 The _How-to_ guides provide practical step-by-step details to help you achieve a particular goal. They are useful when you are trying to get something done but require you to understand and adapt the steps to your specific usecase.
 
 ```{toctree}
-:maxdepth: 2
+:maxdepth: 1
 
+api-only
+proxy
+rest
+separate-proxy
+templates
+upgrading
 ```

docs/source/howto/rest.md

@@ -19,7 +19,7 @@ Hub.
 
 ## What you can do with the API
 
-Using the [JupyterHub REST API][], you can perform actions on the Hub,
+Using the [JupyterHub REST API](jupyterhub-rest-api), you can perform actions on the Hub,
 such as:
 
 - Checking which users are active
@@ -320,7 +320,7 @@ or kubernetes pods.
 
 ## Learn more about the API
 
-You can see the full [JupyterHub REST API][] for more details.
+You can see the full [JupyterHub REST API](jupyterhub-rest-api) for more details.
 
 [openapi initiative]: https://www.openapis.org/
 [jupyterhub rest api]: ./rest-api

docs/source/howto/separate-proxy.md

@@ -1,3 +1,5 @@
+(separate-proxy)= 
+
 # Running proxy separately from the hub
 
 ## Background

docs/source/howto/upgrading.md

@@ -1,3 +1,5 @@
+(upgrading-jupyterhub)=
+
 # Upgrading JupyterHub
 
 JupyterHub offers easy upgrade pathways between minor versions. This

docs/source/index-admin.md

@@ -7,7 +7,6 @@ well as other information relevant to running your own JupyterHub over time.
 :maxdepth: 2
 
 admin/capacity-planning
-admin/upgrading
 admin/log-messages
 changelog
 ```

docs/source/reference/index.md

@@ -12,15 +12,10 @@ websecurity
 authenticators
 spawners
 services
-proxy
-separate-proxy
-rest
 rest-api
 server-api
 monitoring
 database
-templates
-api-only
 ../events/index
 config-user-env
 config-examples

docs/source/reference/rest-api.md

@@ -1,3 +1,5 @@
+(jupyterhub-rest-api)= 
+
 # JupyterHub REST API
 
 Below is an interactive view of JupyterHub's OpenAPI specification.