diff --git a/docs/source/api/index.md b/docs/source/api/index.md deleted file mode 100644 index a6336573..00000000 --- a/docs/source/api/index.md +++ /dev/null @@ -1,37 +0,0 @@ -(api-index)= - -# JupyterHub API - - - -: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/ diff --git a/docs/source/events/index.md b/docs/source/events/index.md index 008f58a9..675b8dc5 100644 --- a/docs/source/events/index.md +++ b/docs/source/events/index.md @@ -1,3 +1,7 @@ + + # 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/howto/rest.md b/docs/source/howto/rest.md index 25be4116..6b5337a0 100644 --- a/docs/source/howto/rest.md +++ b/docs/source/howto/rest.md @@ -57,7 +57,7 @@ jupyterhub token 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: diff --git a/docs/source/howto/upgrading.md b/docs/source/howto/upgrading.md index b7bfa2ce..dc43c8fb 100644 --- a/docs/source/howto/upgrading.md +++ b/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 diff --git a/docs/source/index-about.md b/docs/source/index-about.md index 9372c4e7..5ccb9584 100644 --- a/docs/source/index-about.md +++ b/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 ``` diff --git a/docs/source/index.md b/docs/source/index.md index 2dd53cef..1e1e0e13 100644 --- a/docs/source/index.md +++ b/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 diff --git a/docs/source/api/app.md b/docs/source/reference/api-reference/app.md similarity index 100% rename from docs/source/api/app.md rename to docs/source/reference/api-reference/app.md diff --git a/docs/source/api/auth.md b/docs/source/reference/api-reference/auth.md similarity index 100% rename from docs/source/api/auth.md rename to docs/source/reference/api-reference/auth.md diff --git a/docs/source/api/proxy.md b/docs/source/reference/api-reference/proxy.md similarity index 100% rename from docs/source/api/proxy.md rename to docs/source/reference/api-reference/proxy.md diff --git a/docs/source/api/service.md b/docs/source/reference/api-reference/service.md similarity index 100% rename from docs/source/api/service.md rename to docs/source/reference/api-reference/service.md diff --git a/docs/source/api/services.auth.md b/docs/source/reference/api-reference/services.auth.md similarity index 100% rename from docs/source/api/services.auth.md rename to docs/source/reference/api-reference/services.auth.md diff --git a/docs/source/api/spawner.md b/docs/source/reference/api-reference/spawner.md similarity index 100% rename from docs/source/api/spawner.md rename to docs/source/reference/api-reference/spawner.md diff --git a/docs/source/api/user.md b/docs/source/reference/api-reference/user.md similarity index 100% rename from docs/source/api/user.md rename to docs/source/reference/api-reference/user.md diff --git a/docs/source/reference/index.md b/docs/source/reference/index.md index cc14615b..7733c269 100644 --- a/docs/source/reference/index.md +++ b/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 + + + +: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/ diff --git a/docs/source/reference/rest-api.md b/docs/source/reference/rest-api.md index a7ff0ee4..ce9289f0 100644 --- a/docs/source/reference/rest-api.md +++ b/docs/source/reference/rest-api.md @@ -1,3 +1,6 @@ + (jupyterhub-rest-API)= # JupyterHub REST API diff --git a/docs/source/changelog.md b/docs/source/reference/technical-reference/changelog/changelog.md similarity index 99% rename from docs/source/changelog.md rename to docs/source/reference/technical-reference/changelog/changelog.md index 4c1a8191..e27e7b64 100644 --- a/docs/source/changelog.md +++ b/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. diff --git a/docs/source/reference/config-reference.md b/docs/source/reference/technical-reference/configuration/config-reference.md similarity index 100% rename from docs/source/reference/config-reference.md rename to docs/source/reference/technical-reference/configuration/config-reference.md diff --git a/docs/source/reference/services.md b/docs/source/reference/technical-reference/configuration/services.md similarity index 98% rename from docs/source/reference/services.md rename to docs/source/reference/technical-reference/configuration/services.md index e15c714c..29122284 100644 --- a/docs/source/reference/services.md +++ b/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 ``` diff --git a/docs/source/reference/urls.md b/docs/source/reference/technical-reference/configuration/urls.md similarity index 94% rename from docs/source/reference/urls.md rename to docs/source/reference/technical-reference/configuration/urls.md index 61a92d75..9c5ba6ad 100644 --- a/docs/source/reference/urls.md +++ b/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: diff --git a/docs/source/gallery-jhub-deployments.md b/docs/source/reference/technical-reference/deployments/gallery-jhub-deployments.md similarity index 100% rename from docs/source/gallery-jhub-deployments.md rename to docs/source/reference/technical-reference/deployments/gallery-jhub-deployments.md diff --git a/docs/source/reference/monitoring.md b/docs/source/reference/technical-reference/monitoring/monitoring.md similarity index 97% rename from docs/source/reference/monitoring.md rename to docs/source/reference/technical-reference/monitoring/monitoring.md index cbd5964f..a1a01635 100644 --- a/docs/source/reference/monitoring.md +++ b/docs/source/reference/technical-reference/monitoring/monitoring.md @@ -16,5 +16,5 @@ tool like [Grafana](https://grafana.com). ```{toctree} :maxdepth: 2 -metrics +/reference/metrics ``` diff --git a/docs/source/reference/authenticators.md b/docs/source/reference/technical-reference/subsystems/authenticators.md similarity index 99% rename from docs/source/reference/authenticators.md rename to docs/source/reference/technical-reference/subsystems/authenticators.md index a81be9f0..439b5ffa 100644 --- a/docs/source/reference/authenticators.md +++ b/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 diff --git a/docs/source/reference/spawners.md b/docs/source/reference/technical-reference/subsystems/spawners.md similarity index 99% rename from docs/source/reference/spawners.md rename to docs/source/reference/technical-reference/subsystems/spawners.md index 653f4c9b..b89158f2 100644 --- a/docs/source/reference/spawners.md +++ b/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. diff --git a/docs/source/reference/technical-overview.md b/docs/source/reference/technical-reference/technical-overview.md similarity index 90% rename from docs/source/reference/technical-overview.md rename to docs/source/reference/technical-reference/technical-overview.md index 79e0f8c3..270248b5 100644 --- a/docs/source/reference/technical-overview.md +++ b/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.