diff --git a/docs/source/explanation/admin/capacity-planning.md b/docs/source/explanation/capacity-planning.md similarity index 100% rename from docs/source/explanation/admin/capacity-planning.md rename to docs/source/explanation/capacity-planning.md diff --git a/docs/source/explanation/admin/database.md b/docs/source/explanation/database.md similarity index 100% rename from docs/source/explanation/admin/database.md rename to docs/source/explanation/database.md diff --git a/docs/source/explanation/index.md b/docs/source/explanation/index.md index b8e634c2..22dd5189 100644 --- a/docs/source/explanation/index.md +++ b/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 -admin/database -admin/websecurity -admin/oauth +capacity-planning +database +websecurity +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. - -```{toctree} -:maxdepth: 2 - -../rbac/index -``` diff --git a/docs/source/explanation/admin/oauth.md b/docs/source/explanation/oauth.md similarity index 100% rename from docs/source/explanation/admin/oauth.md rename to docs/source/explanation/oauth.md diff --git a/docs/source/explanation/admin/websecurity.md b/docs/source/explanation/websecurity.md similarity index 100% rename from docs/source/explanation/admin/websecurity.md rename to docs/source/explanation/websecurity.md diff --git a/docs/source/howto/index.md b/docs/source/howto/index.md index 6acaa46d..837d5f58 100644 --- a/docs/source/howto/index.md +++ b/docs/source/howto/index.md @@ -14,6 +14,7 @@ separate-proxy templates upgrading log-messages + ``` (config-examples)= diff --git a/docs/source/redirects.txt b/docs/source/redirects.txt index 87096dd4..7c51ea7c 100644 --- a/docs/source/redirects.txt +++ b/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" -"quickstart.md" "tutorial/installation/quickstart.md" +"installation-basics.md" "tutorial/installation-basics.md" +"quickstart.md" "tutorial/quickstart.md" diff --git a/docs/source/reference/technical-reference/subsystems/authenticators.md b/docs/source/reference/authenticators.md similarity index 100% rename from docs/source/reference/technical-reference/subsystems/authenticators.md rename to docs/source/reference/authenticators.md diff --git a/docs/source/reference/technical-reference/changelog/changelog.md b/docs/source/reference/changelog.md similarity index 100% rename from docs/source/reference/technical-reference/changelog/changelog.md rename to docs/source/reference/changelog.md diff --git a/docs/source/reference/technical-reference/configuration/config-reference.md b/docs/source/reference/config-reference.md similarity index 100% rename from docs/source/reference/technical-reference/configuration/config-reference.md rename to docs/source/reference/config-reference.md diff --git a/docs/source/events/index.md b/docs/source/reference/event-logging.md similarity index 92% rename from docs/source/events/index.md rename to docs/source/reference/event-logging.md index 95a5c2dc..008f58a9 100644 --- a/docs/source/events/index.md +++ b/docs/source/reference/event-logging.md @@ -1,7 +1,3 @@ - - # 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]. diff --git a/docs/source/reference/technical-reference/deployments/gallery-jhub-deployments.md b/docs/source/reference/gallery-jhub-deployments.md similarity index 100% rename from docs/source/reference/technical-reference/deployments/gallery-jhub-deployments.md rename to docs/source/reference/gallery-jhub-deployments.md diff --git a/docs/source/reference/index.md b/docs/source/reference/index.md index b778d1a3..fc464bee 100644 --- a/docs/source/reference/index.md +++ b/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 -``` - -### 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 +technical-overview +authenticators +spawners +config-reference +services +urls +event-logging +monitoring +gallery-jhub-deployments +changelog ``` --- -(api-index)= - ## API reference - - - -: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 +reference-api/index.md ``` -[openapi initiative]: https://www.openapis.org/ diff --git a/docs/source/reference/technical-reference/monitoring/monitoring.md b/docs/source/reference/monitoring.md similarity index 100% rename from docs/source/reference/technical-reference/monitoring/monitoring.md rename to docs/source/reference/monitoring.md diff --git a/docs/source/reference/api-reference/app.md b/docs/source/reference/reference-api/app.md similarity index 100% rename from docs/source/reference/api-reference/app.md rename to docs/source/reference/reference-api/app.md diff --git a/docs/source/reference/api-reference/auth.md b/docs/source/reference/reference-api/auth.md similarity index 100% rename from docs/source/reference/api-reference/auth.md rename to docs/source/reference/reference-api/auth.md diff --git a/docs/source/reference/reference-api/index.md b/docs/source/reference/reference-api/index.md new file mode 100644 index 00000000..aea3e03b --- /dev/null +++ b/docs/source/reference/reference-api/index.md @@ -0,0 +1,36 @@ +(api-index)= + +# JupyterHub API Reference + + +: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/ + diff --git a/docs/source/reference/api-reference/proxy.md b/docs/source/reference/reference-api/proxy.md similarity index 100% rename from docs/source/reference/api-reference/proxy.md rename to docs/source/reference/reference-api/proxy.md diff --git a/docs/source/reference/api-reference/service.md b/docs/source/reference/reference-api/service.md similarity index 100% rename from docs/source/reference/api-reference/service.md rename to docs/source/reference/reference-api/service.md diff --git a/docs/source/reference/api-reference/services.auth.md b/docs/source/reference/reference-api/services.auth.md similarity index 100% rename from docs/source/reference/api-reference/services.auth.md rename to docs/source/reference/reference-api/services.auth.md diff --git a/docs/source/reference/api-reference/spawner.md b/docs/source/reference/reference-api/spawner.md similarity index 100% rename from docs/source/reference/api-reference/spawner.md rename to docs/source/reference/reference-api/spawner.md diff --git a/docs/source/reference/api-reference/user.md b/docs/source/reference/reference-api/user.md similarity index 100% rename from docs/source/reference/api-reference/user.md rename to docs/source/reference/reference-api/user.md diff --git a/docs/source/events/server-actions.md b/docs/source/reference/server-actions.md similarity index 100% rename from docs/source/events/server-actions.md rename to docs/source/reference/server-actions.md diff --git a/docs/source/reference/technical-reference/configuration/services.md b/docs/source/reference/services.md similarity index 98% rename from docs/source/reference/technical-reference/configuration/services.md rename to docs/source/reference/services.md index 29122284..4770d61e 100644 --- a/docs/source/reference/technical-reference/configuration/services.md +++ b/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 ``` diff --git a/docs/source/reference/technical-reference/subsystems/spawners.md b/docs/source/reference/spawners.md similarity index 100% rename from docs/source/reference/technical-reference/subsystems/spawners.md rename to docs/source/reference/spawners.md diff --git a/docs/source/reference/technical-reference/technical-overview.md b/docs/source/reference/technical-overview.md similarity index 100% rename from docs/source/reference/technical-reference/technical-overview.md rename to docs/source/reference/technical-overview.md diff --git a/docs/source/reference/technical-reference/configuration/urls.md b/docs/source/reference/urls.md similarity index 100% rename from docs/source/reference/technical-reference/configuration/urls.md rename to docs/source/reference/urls.md diff --git a/docs/source/tutorial/index.md b/docs/source/tutorial/index.md index f4c80d88..98aecd5e 100644 --- a/docs/source/tutorial/index.md +++ b/docs/source/tutorial/index.md @@ -11,9 +11,9 @@ running on your own infrastructure. ```{toctree} :maxdepth: 1 -installation/quickstart -installation/installation-basics -installation/quickstart-docker +quickstart +installation-basics +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 ``` diff --git a/docs/source/tutorial/installation/installation-basics.md b/docs/source/tutorial/installation-basics.md similarity index 100% rename from docs/source/tutorial/installation/installation-basics.md rename to docs/source/tutorial/installation-basics.md diff --git a/docs/source/tutorial/installation/quickstart-docker.md b/docs/source/tutorial/quickstart-docker.md similarity index 100% rename from docs/source/tutorial/installation/quickstart-docker.md rename to docs/source/tutorial/quickstart-docker.md diff --git a/docs/source/tutorial/installation/quickstart.md b/docs/source/tutorial/quickstart.md similarity index 100% rename from docs/source/tutorial/installation/quickstart.md rename to docs/source/tutorial/quickstart.md diff --git a/docs/source/tutorial/api/server-api.md b/docs/source/tutorial/server-api.md similarity index 97% rename from docs/source/tutorial/api/server-api.md rename to docs/source/tutorial/server-api.md index 4e8fa1f6..e87530d0 100644 --- a/docs/source/tutorial/api/server-api.md +++ b/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