diff --git a/docs/source/changelog.md b/docs/source/changelog.md index 86192a46..523a6b77 100644 --- a/docs/source/changelog.md +++ b/docs/source/changelog.md @@ -1,3 +1,5 @@ +(changelog)= + # Changelog For detailed changes from the prior release, click on the version number, and diff --git a/docs/source/getting-started/index.md b/docs/source/getting-started/index.md deleted file mode 100644 index d02a3741..00000000 --- a/docs/source/getting-started/index.md +++ /dev/null @@ -1,17 +0,0 @@ -# Get Started - -This section covers how to configure and customize JupyterHub for your -needs. It contains information about authentication, networking, security, and -other topics that are relevant to individuals or organizations deploying their -own JupyterHub. - -```{toctree} -:maxdepth: 2 - -config-basics -networking-basics -security-basics -authenticators-users-basics -spawners-basics -services-basics -``` diff --git a/docs/source/index.md b/docs/source/index.md index 6f468935..f62e5830 100644 --- a/docs/source/index.md +++ b/docs/source/index.md @@ -81,13 +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_. -### Getting Started - -```{toctree} -:maxdepth: 2 - -getting-started/index -``` ### Technical Reference diff --git a/docs/source/reference/index.md b/docs/source/reference/index.md index c7866360..5a253089 100644 --- a/docs/source/reference/index.md +++ b/docs/source/reference/index.md @@ -1,3 +1,5 @@ +(reference-index)= + # Technical Reference This section covers more of the details of the JupyterHub architecture, as well as @@ -13,7 +15,6 @@ authenticators spawners services rest-api -server-api monitoring database ../events/index diff --git a/docs/source/reference/technical-overview.md b/docs/source/reference/technical-overview.md index 9ce3f4f2..79e0f8c3 100644 --- a/docs/source/reference/technical-overview.md +++ b/docs/source/reference/technical-overview.md @@ -110,7 +110,7 @@ working directory: This file needs to persist so that a **Hub** server restart will avoid invalidating cookies. Conversely, deleting this file and restarting the server effectively invalidates all login cookies. The cookie secret file is discussed - in the [Cookie Secret section of the Security Settings document](../getting-started/security-basics.md). + in the [Cookie Secret section of the Security Settings document](security-basics). The location of these files can be specified via configuration settings. It is recommended that these files be stored in standard UNIX filesystem locations, diff --git a/docs/source/reference/server-api.md b/docs/source/tutorial/api/server-api.md similarity index 97% rename from docs/source/reference/server-api.md rename to docs/source/tutorial/api/server-api.md index e87530d0..4e8fa1f6 100644 --- a/docs/source/reference/server-api.md +++ b/docs/source/tutorial/api/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 diff --git a/docs/source/getting-started/authenticators-users-basics.md b/docs/source/tutorial/getting-started/authenticators-users-basics.md similarity index 100% rename from docs/source/getting-started/authenticators-users-basics.md rename to docs/source/tutorial/getting-started/authenticators-users-basics.md diff --git a/docs/source/getting-started/config-basics.md b/docs/source/tutorial/getting-started/config-basics.md similarity index 98% rename from docs/source/getting-started/config-basics.md rename to docs/source/tutorial/getting-started/config-basics.md index 0b22a995..3a9f0ca4 100644 --- a/docs/source/getting-started/config-basics.md +++ b/docs/source/tutorial/getting-started/config-basics.md @@ -1,7 +1,7 @@ # Configuration Basics This section contains basic information about configuring settings for a JupyterHub -deployment. The [Technical Reference](../reference/index) +deployment. The [Technical Reference](reference-index) documentation provides additional details. This section will help you learn how to: diff --git a/docs/source/getting-started/networking-basics.md b/docs/source/tutorial/getting-started/networking-basics.md similarity index 100% rename from docs/source/getting-started/networking-basics.md rename to docs/source/tutorial/getting-started/networking-basics.md diff --git a/docs/source/getting-started/security-basics.md b/docs/source/tutorial/getting-started/security-basics.md similarity index 100% rename from docs/source/getting-started/security-basics.md rename to docs/source/tutorial/getting-started/security-basics.md diff --git a/docs/source/getting-started/services-basics.md b/docs/source/tutorial/getting-started/services-basics.md similarity index 93% rename from docs/source/getting-started/services-basics.md rename to docs/source/tutorial/getting-started/services-basics.md index 5ec3f779..ae23912e 100644 --- a/docs/source/getting-started/services-basics.md +++ b/docs/source/tutorial/getting-started/services-basics.md @@ -14,7 +14,7 @@ document will: - explain some basic information about API tokens - clarify that API tokens can be used to authenticate to - single-user servers as of [version 0.8.0](../changelog) + single-user servers as of [version 0.8.0](changelog) - show how the [jupyterhub_idle_culler][] script can be: - used in a Hub-managed service - run as a standalone script @@ -29,19 +29,19 @@ Hub via the REST API. To run such an external service, an API token must be created and provided to the service. -As of [version 0.6.0](../changelog), the preferred way of doing +As of [version 0.6.0](changelog), the preferred way of doing this is to first generate an API token: ```bash openssl rand -hex 32 ``` -In [version 0.8.0](../changelog), 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: -![Request API TOKEN page](../images/token-request.png) +![Request API TOKEN page](/images/token-request.png) -![API TOKEN success page](../images/token-request-success.png) +![API TOKEN success page](/images/token-request-success.png) ### Step 2: Pass environment variable with token to the Hub diff --git a/docs/source/getting-started/spawners-basics.md b/docs/source/tutorial/getting-started/spawners-basics.md similarity index 100% rename from docs/source/getting-started/spawners-basics.md rename to docs/source/tutorial/getting-started/spawners-basics.md diff --git a/docs/source/tutorial/index.md b/docs/source/tutorial/index.md index 9fa671d0..490dd00f 100644 --- a/docs/source/tutorial/index.md +++ b/docs/source/tutorial/index.md @@ -1,10 +1,10 @@ # Tutorials -This section of the documentation provides step-by-step tutorials to help you achieve a specific goal. The tutorials should be a good place to start learning about JupyterHub and how it works. +The *Tutorials* provide step-by-step lessons to help you achieve a specific goal. The tutorials should be a good place to start learning about JupyterHub and how it works. ## Installation -These sections cover how to get up-and-running with JupyterHub. They cover +This section covers how to get up-and-running with JupyterHub. It covers some basics of the tools needed to deploy JupyterHub as well as how to get it running on your own infrastructure. @@ -15,3 +15,31 @@ installation/quickstart installation/installation-basics installation/quickstart-docker ``` + +## Getting Started + +This section covers how to configure and customize JupyterHub for your +needs. It contains information about authentication, networking, security, and +other topics that are relevant to individuals or organizations deploying their +own JupyterHub. + +```{toctree} +:maxdepth: 1 + +getting-started/config-basics +getting-started/networking-basics +getting-started/security-basics +getting-started/authenticators-users-basics +getting-started/services-basics +getting-started/spawners-basics +``` + +## Working with the JupyterHub API + +JupyterHub's functionalities can be accessed using its API. In this section, we cover how to use the JupyterHub API to achieve specific goals, for example, starting servers. + +```{toctree} +:maxdepth: 1 + +api/server-api +``` \ No newline at end of file