diff --git a/docs/source/contributing/community.md b/docs/source/contributing/community.md index 84c5a83d3f..8da0e871fb 100644 --- a/docs/source/contributing/community.md +++ b/docs/source/contributing/community.md @@ -1,3 +1,5 @@ +(contributing:community)= + # Community communication channels We use different channels of communication for different purposes. Whichever one you use will depend on what kind of communication you want to engage in. diff --git a/docs/source/contributing/contributor-list.md b/docs/source/contributing/contributor-list.md index f26736718c..75ed2c2063 100644 --- a/docs/source/contributing/contributor-list.md +++ b/docs/source/contributing/contributor-list.md @@ -1,3 +1,5 @@ +(contributing:contributors)= + # Contributors Project Jupyter thanks the following people for their help and diff --git a/docs/source/contributing/docs.md b/docs/source/contributing/docs.md index f3ad71ca2a..c2a3b4ac2c 100644 --- a/docs/source/contributing/docs.md +++ b/docs/source/contributing/docs.md @@ -1,4 +1,4 @@ -(contributing-docs)= +(contributing:docs)= # Contributing Documentation @@ -13,7 +13,7 @@ stored under the `docs/source` directory) and converts it into various formats for people to read. To make sure the documentation you write or change renders correctly, it is good practice to test it locally. -1. Make sure you have successfully completed {ref}`contributing/setup`. +1. Make sure you have successfully completed {ref}`contributing:setup`. 2. Install the packages required to build the docs. diff --git a/docs/source/contributing/index.md b/docs/source/contributing/index.md index 79a816513e..3c32871882 100644 --- a/docs/source/contributing/index.md +++ b/docs/source/contributing/index.md @@ -1,3 +1,5 @@ +(contributing)= + # Contributing We want you to contribute to JupyterHub in ways that are most exciting diff --git a/docs/source/contributing/roadmap.md b/docs/source/contributing/roadmap.md index 5f2bc49c6f..0510eb948a 100644 --- a/docs/source/contributing/roadmap.md +++ b/docs/source/contributing/roadmap.md @@ -1,3 +1,5 @@ +(contributing:roadmap)= + # The JupyterHub roadmap This roadmap collects "next steps" for JupyterHub. It is about creating a diff --git a/docs/source/contributing/security.md b/docs/source/contributing/security.md index 66dc294d7d..6a882a33b2 100644 --- a/docs/source/contributing/security.md +++ b/docs/source/contributing/security.md @@ -1,7 +1,9 @@ +(contributing:security)= + # Reporting security issues in Jupyter or JupyterHub If you find a security vulnerability in Jupyter or JupyterHub, -whether it is a failure of the security model described in [Security Overview](web-security) +whether it is a failure of the security model described in [Security Overview](explanation:security) or a failure in implementation, please report it to . diff --git a/docs/source/contributing/setup.md b/docs/source/contributing/setup.md index 161f0ac3b0..2f97577d90 100644 --- a/docs/source/contributing/setup.md +++ b/docs/source/contributing/setup.md @@ -1,4 +1,4 @@ -(contributing/setup)= +(contributing:setup)= # Setting up a development install diff --git a/docs/source/contributing/tests.md b/docs/source/contributing/tests.md index 1f5831bca0..350d6c939f 100644 --- a/docs/source/contributing/tests.md +++ b/docs/source/contributing/tests.md @@ -11,7 +11,7 @@ can find them under the [jupyterhub/tests](https://github.com/jupyterhub/jupyter ## Running the tests -1. Make sure you have completed {ref}`contributing/setup`. +1. Make sure you have completed {ref}`contributing:setup`. Once you are done, you would be able to run `jupyterhub` from the command line and access it from your web browser. This ensures that the dev environment is properly set up for tests to run. @@ -126,7 +126,7 @@ For more information on asyncio and event-loops, here are some resources: ### All the tests are failing -Make sure you have completed all the steps in {ref}`contributing/setup` successfully, and are able to access JupyterHub from your browser at http://localhost:8000 after starting `jupyterhub` in your command line. +Make sure you have completed all the steps in {ref}`contributing:setup` successfully, and are able to access JupyterHub from your browser at http://localhost:8000 after starting `jupyterhub` in your command line. ## Code formatting and linting diff --git a/docs/source/explanation/capacity-planning.md b/docs/source/explanation/capacity-planning.md index 4b122b1b46..a663389027 100644 --- a/docs/source/explanation/capacity-planning.md +++ b/docs/source/explanation/capacity-planning.md @@ -1,3 +1,5 @@ +(explanation:capacity-planning)= + # Capacity planning General capacity planning advice for JupyterHub is hard to give, diff --git a/docs/source/explanation/concepts.md b/docs/source/explanation/concepts.md index 1b1b3ab1af..32abae8c0f 100644 --- a/docs/source/explanation/concepts.md +++ b/docs/source/explanation/concepts.md @@ -1,3 +1,5 @@ +(explanation:concepts)= + # JupyterHub: A conceptual overview ```{warning} @@ -201,7 +203,7 @@ running, the notebooks). By default, the hub starts the proxy automatically and stops the proxy when the hub stops (so that connections get interrupted). But when you [configure the proxy to run -separately](separate-proxy), +separately](howto:separate-proxy), user's connections will continue to work even without the hub. The default proxy is **ConfigurableHttpProxy** which is simple but diff --git a/docs/source/explanation/database.md b/docs/source/explanation/database.md index 1990da0d1f..e35eb042f0 100644 --- a/docs/source/explanation/database.md +++ b/docs/source/explanation/database.md @@ -1,4 +1,4 @@ -(hub-database)= +(explanation:hub-database)= # The Hub's Database diff --git a/docs/source/explanation/index.md b/docs/source/explanation/index.md index d8bc63f9c5..63116cb910 100644 --- a/docs/source/explanation/index.md +++ b/docs/source/explanation/index.md @@ -1,3 +1,5 @@ +(explanation)= + # Explanation _Explanation_ documentation provide big-picture descriptions of how JupyterHub works. This section is meant to build your understanding of particular topics. diff --git a/docs/source/explanation/oauth.md b/docs/source/explanation/oauth.md index 38b507ae25..2cdf490b64 100644 --- a/docs/source/explanation/oauth.md +++ b/docs/source/explanation/oauth.md @@ -1,4 +1,4 @@ -(jupyterhub-oauth)= +(explanation:hub-oauth)= # JupyterHub and OAuth diff --git a/docs/source/explanation/singleuser.md b/docs/source/explanation/singleuser.md index e4618ce8a5..59b5260ee7 100644 --- a/docs/source/explanation/singleuser.md +++ b/docs/source/explanation/singleuser.md @@ -1,4 +1,4 @@ -(singleuser)= +(explanation:singleuser)= # The JupyterHub single-user server diff --git a/docs/source/explanation/websecurity.md b/docs/source/explanation/websecurity.md index ac92dab3ae..7b049ed88d 100644 --- a/docs/source/explanation/websecurity.md +++ b/docs/source/explanation/websecurity.md @@ -1,4 +1,4 @@ -(web-security)= +(explanation:security)= # Security Overview diff --git a/docs/source/faq/faq.md b/docs/source/faq/faq.md index a1df47e068..a82d63502f 100644 --- a/docs/source/faq/faq.md +++ b/docs/source/faq/faq.md @@ -1,3 +1,5 @@ +(faq)= + # Frequently asked questions ## How do I share links to notebooks? diff --git a/docs/source/faq/institutional-faq.md b/docs/source/faq/institutional-faq.md index c0d9f303bb..3308a3e508 100644 --- a/docs/source/faq/institutional-faq.md +++ b/docs/source/faq/institutional-faq.md @@ -1,3 +1,5 @@ +(faq:institutional)= + # Institutional FAQ This page contains common questions from users of JupyterHub, @@ -130,7 +132,7 @@ level for several years, and makes a number of "default" security decisions that users. - For security considerations in the base JupyterHub application, - [see the JupyterHub security page](web-security). + [see the JupyterHub security page](explanation:security). - For security considerations when deploying JupyterHub on Kubernetes, see the [JupyterHub on Kubernetes security page](https://z2jh.jupyter.org/en/latest/security.html). diff --git a/docs/source/faq/troubleshooting.md b/docs/source/faq/troubleshooting.md index 98e0d438c5..0f5e3d1d0d 100644 --- a/docs/source/faq/troubleshooting.md +++ b/docs/source/faq/troubleshooting.md @@ -1,4 +1,4 @@ -(troubleshooting)= +(faq:troubleshooting)= # Troubleshooting diff --git a/docs/source/howto/api-only.md b/docs/source/howto/api-only.md index c265468d54..be1967b009 100644 --- a/docs/source/howto/api-only.md +++ b/docs/source/howto/api-only.md @@ -1,4 +1,4 @@ -(api-only)= +(howto:api-only)= # Deploying JupyterHub in "API only mode" diff --git a/docs/source/howto/configuration/config-ghoauth.md b/docs/source/howto/configuration/config-ghoauth.md index bd8e290b1d..5ef91c1bcd 100644 --- a/docs/source/howto/configuration/config-ghoauth.md +++ b/docs/source/howto/configuration/config-ghoauth.md @@ -1,3 +1,5 @@ +(howto:config:gh-oauth)= + # Configure GitHub OAuth In this example, we show a configuration file for a fairly standard JupyterHub diff --git a/docs/source/howto/configuration/config-proxy.md b/docs/source/howto/configuration/config-proxy.md index 04efad6ff3..8a171254a5 100644 --- a/docs/source/howto/configuration/config-proxy.md +++ b/docs/source/howto/configuration/config-proxy.md @@ -1,3 +1,5 @@ +(howto:config:reverse-proxy)= + # Using a reverse proxy In the following example, we show configuration files for a JupyterHub server diff --git a/docs/source/howto/configuration/config-sudo.md b/docs/source/howto/configuration/config-sudo.md index ea24575976..d4c35f2722 100644 --- a/docs/source/howto/configuration/config-sudo.md +++ b/docs/source/howto/configuration/config-sudo.md @@ -1,3 +1,5 @@ +(howto:config:no-sudo)= + # Run JupyterHub without root privileges using `sudo` **Note:** Setting up `sudo` permissions involves many pieces of system diff --git a/docs/source/howto/configuration/config-user-env.md b/docs/source/howto/configuration/config-user-env.md index 39b2f2da28..f01595b321 100644 --- a/docs/source/howto/configuration/config-user-env.md +++ b/docs/source/howto/configuration/config-user-env.md @@ -1,3 +1,5 @@ +(howto:config:user-env)= + # Configuring user environments To deploy JupyterHub means you are providing Jupyter notebook environments for diff --git a/docs/source/howto/log-messages.md b/docs/source/howto/log-messages.md index cda307df27..26f16f680b 100644 --- a/docs/source/howto/log-messages.md +++ b/docs/source/howto/log-messages.md @@ -1,3 +1,5 @@ +(howto:log-messages)= + # Interpreting common log messages When debugging errors and outages, looking at the logs emitted by diff --git a/docs/source/howto/proxy.md b/docs/source/howto/proxy.md index f0cfa974b8..e5dbbf8cc3 100644 --- a/docs/source/howto/proxy.md +++ b/docs/source/howto/proxy.md @@ -1,3 +1,5 @@ +(howto:custom-proxy)= + # Writing a custom Proxy implementation JupyterHub 0.8 introduced the ability to write a custom implementation of the diff --git a/docs/source/howto/rest.md b/docs/source/howto/rest.md index b7e2e88074..7822cc13dc 100644 --- a/docs/source/howto/rest.md +++ b/docs/source/howto/rest.md @@ -1,4 +1,4 @@ -(using-jupyterhub-rest-api)= +(howto:rest-api)= # Using JupyterHub's REST API diff --git a/docs/source/howto/separate-proxy.md b/docs/source/howto/separate-proxy.md index 084db4a10c..a4228d3bd2 100644 --- a/docs/source/howto/separate-proxy.md +++ b/docs/source/howto/separate-proxy.md @@ -1,4 +1,4 @@ -(separate-proxy)= +(howto:separate-proxy)= # Running proxy separately from the hub diff --git a/docs/source/howto/templates.md b/docs/source/howto/templates.md index 44ca87d43f..588dc86518 100644 --- a/docs/source/howto/templates.md +++ b/docs/source/howto/templates.md @@ -1,3 +1,5 @@ +(howto:templates)= + # Working with templates and UI The pages of the JupyterHub application are generated from diff --git a/docs/source/howto/upgrading-v5.md b/docs/source/howto/upgrading-v5.md index 1490884211..91fe7faf48 100644 --- a/docs/source/howto/upgrading-v5.md +++ b/docs/source/howto/upgrading-v5.md @@ -1,4 +1,4 @@ -(upgrading-v5)= +(howto:upgrading-v5)= # Upgrading to JupyterHub 5 diff --git a/docs/source/howto/upgrading.md b/docs/source/howto/upgrading.md index 4655a69887..6e07db2c58 100644 --- a/docs/source/howto/upgrading.md +++ b/docs/source/howto/upgrading.md @@ -1,4 +1,4 @@ -(upgrading-jupyterhub)= +(howto:upgrading-jupyterhub)= # Upgrading JupyterHub diff --git a/docs/source/rbac/scopes.md b/docs/source/rbac/scopes.md index 96cd338526..b407b5399f 100644 --- a/docs/source/rbac/scopes.md +++ b/docs/source/rbac/scopes.md @@ -186,14 +186,14 @@ An **access scope** is used to govern _access_ to a JupyterHub service or a user This means making API requests, or visiting via a browser using OAuth. Without the appropriate access scope, a user or token should not be permitted to make requests of the service. -When you attempt to access a service or server authenticated with JupyterHub, it will begin the [oauth flow](jupyterhub-oauth) for issuing a token that can be used to access the service. +When you attempt to access a service or server authenticated with JupyterHub, it will begin the [oauth flow](explanation:hub-oauth) for issuing a token that can be used to access the service. If the user does not have the access scope for the relevant service or server, JupyterHub will not permit the oauth process to complete. If oauth completes, the token will have at least the access scope for the service. For minimal permissions, this is the _only_ scope granted to tokens issued during oauth by default, but can be expanded via {attr}`.Spawner.oauth_client_allowed_scopes` or a service's [`oauth_client_allowed_scopes`](service-credentials) configuration. :::{seealso} -[Further explanation of OAuth in JupyterHub](jupyterhub-oauth) +[Further explanation of OAuth in JupyterHub](explanation:hub-oauth) ::: If a given service or single-user server can be governed by a single boolean "yes, you can use this service" or "no, you can't," or limiting via other existing scopes, access scopes are enough to manage access to the service. diff --git a/docs/source/rbac/upgrade.md b/docs/source/rbac/upgrade.md index 22f017bd63..25897a374e 100644 --- a/docs/source/rbac/upgrade.md +++ b/docs/source/rbac/upgrade.md @@ -11,7 +11,7 @@ No other database records are affected. ## Upgrade steps 1. All running **servers must be stopped** before proceeding with the upgrade. -2. To upgrade the Hub, follow the [Upgrading JupyterHub](upgrading-jupyterhub) instructions. +2. To upgrade the Hub, follow the [Upgrading JupyterHub](howto:upgrading-jupyterhub) instructions. ```{attention} We advise against defining any new roles in the `jupyterhub.config.py` file right after the upgrade is completed and JupyterHub restarted for the first time. This preserves the 'current' state of the Hub. You can define and assign new roles on any other following startup. ``` diff --git a/docs/source/reference/api/index.md b/docs/source/reference/api/index.md index 18cf49d572..1673c331d1 100644 --- a/docs/source/reference/api/index.md +++ b/docs/source/reference/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](using-jupyterhub-rest-api) provides +The documentation on [Using JupyterHub's REST API](howto:rest-api) provides information on: - what you can do with the API diff --git a/docs/source/reference/changelog.md b/docs/source/reference/changelog.md index 72762c1e8f..955d18f43b 100644 --- a/docs/source/reference/changelog.md +++ b/docs/source/reference/changelog.md @@ -27,7 +27,7 @@ Contributors to major version bumps in JupyterHub include: 5.0.0 is a major release of JupyterHub. It has lots of cool new features. -For information about upgrading, see [upgrading to 5.0 documentation](upgrading-v5). +For information about upgrading, see [upgrading to 5.0 documentation](howto:upgrading-v5). Changes that are likely to require effort to upgrade: @@ -298,7 +298,7 @@ especially those with other user content on peer domains to JupyterHub. As always, JupyterHub deployments are especially encouraged to enable per-user domains if protecting users from each other is a concern. -For more information on securely deploying JupyterHub, see the [web security documentation](web-security). +For more information on securely deploying JupyterHub, see the [web security documentation](explanation:security). [CVE-2024-28233]: https://github.com/jupyterhub/jupyterhub/security/advisories/GHSA-7r3h-4ph8-w38g @@ -422,13 +422,13 @@ See [our definition of contributors](https://github-activity.readthedocs.io/en/l :::{admonition} Upgrade note Upgrading from 3.1 to 4.0 should require no additional action beyond running `jupyterhub --upgrade-db` to upgrade the database schema after upgrading the package version. -It is otherwise a regular jupyterhub [upgrade](upgrading-jupyterhub). +It is otherwise a regular jupyterhub [upgrade](howto:upgrading-jupyterhub). ::: There are three major changes that _should_ be invisible to most users: 1. Groups can now have 'properties', editable via the admin page, which can be used by Spawners for their operations. - This requires a db schema upgrade, so remember to [**backup and upgrade your database**](upgrading-jupyterhub)! + This requires a db schema upgrade, so remember to [**backup and upgrade your database**](howto:upgrading-jupyterhub)! 2. Often-problematic header-based checks for cross-site requests have been replaces with more standard use of XSRF tokens. Most folks shouldn't notice this change, but if "Blocking Cross Origin API request" has been giving you headaches, this should be much improved. 3. Improved support for Jupyter Server 2.0 by reimplementing `jupyterhub-singleuser` as a standard _server extension_. @@ -1136,7 +1136,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](upgrading-jupyterhub) +so **make sure to [read the upgrade documentation and backup your database](howto:upgrading-jupyterhub) before upgrading**. :::{admonition} stop all servers before upgrading diff --git a/docs/source/reference/services.md b/docs/source/reference/services.md index 3cd84214c4..b09a2f94dd 100644 --- a/docs/source/reference/services.md +++ b/docs/source/reference/services.md @@ -213,7 +213,7 @@ c.JupyterHub.load_roles = [ ] ``` -When a service has a configured URL or explicit `oauth_client_id` or `oauth_redirect_uri`, it can operate as an [OAuth client](jupyterhub-oauth). +When a service has a configured URL or explicit `oauth_client_id` or `oauth_redirect_uri`, it can operate as an [OAuth client](explanation:hub-oauth). When a user visits an oauth-authenticated service, completion of authentication results in issuing an oauth token. diff --git a/docs/source/reference/urls.md b/docs/source/reference/urls.md index 9c5ba6adb1..d8bf071eda 100644 --- a/docs/source/reference/urls.md +++ b/docs/source/reference/urls.md @@ -4,7 +4,7 @@ This document describes how JupyterHub routes requests. -This does not include the [REST API](using-jupyterhub-rest-api) URLs. +This does not include the [REST API](howto:rest-api) URLs. In general, all URLs can be prefixed with `c.JupyterHub.base_url` to run the whole JupyterHub application on a prefix. @@ -240,7 +240,7 @@ and the page will show a link back to `/hub/spawn/...`. On this page, users can manage their JupyterHub API tokens. They can revoke access and request new tokens for writing scripts -against the [JupyterHub REST API](using-jupyterhub-rest-api). +against the [JupyterHub REST API](howto:rest-api). ## `/hub/admin` diff --git a/docs/source/tutorial/getting-started/config-basics.md b/docs/source/tutorial/getting-started/config-basics.md index 3a9f0ca4ab..9c176a70f1 100644 --- a/docs/source/tutorial/getting-started/config-basics.md +++ b/docs/source/tutorial/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](separate-proxy). +for information see [the separate proxy page](howto:separate-proxy). diff --git a/docs/source/tutorial/getting-started/security-basics.md b/docs/source/tutorial/getting-started/security-basics.md index 806008d5c0..be5be63105 100644 --- a/docs/source/tutorial/getting-started/security-basics.md +++ b/docs/source/tutorial/getting-started/security-basics.md @@ -43,7 +43,7 @@ is important that these files be put in a secure location on your server, where they are not readable by regular users. If you are using a **chain certificate**, see also chained certificate for SSL -in the JupyterHub [Troubleshooting FAQ](troubleshooting). +in the JupyterHub [Troubleshooting FAQ](faq:troubleshooting). ### Using letsencrypt diff --git a/docs/source/tutorial/server-api.md b/docs/source/tutorial/server-api.md index e87530d068..32632919ff 100644 --- a/docs/source/tutorial/server-api.md +++ b/docs/source/tutorial/server-api.md @@ -1,7 +1,7 @@ # Starting servers with the JupyterHub API Sometimes, when working with applications such as [BinderHub](https://binderhub.readthedocs.io), it may be necessary to launch Jupyter-based services on behalf of your users. -Doing so can be achieved through JupyterHub's [REST API](using-jupyterhub-rest-api), which allows one to launch and manage servers on behalf of users through API calls instead of the JupyterHub UI. +Doing so can be achieved through JupyterHub's [REST API](howto:rest-api), which allows one to launch and manage servers on behalf of users through API calls instead of the JupyterHub UI. This way, you can take advantage of other user/launch/lifecycle patterns that are not natively supported by the JupyterHub UI, all without the need to develop the server management features of JupyterHub Spawners and/or Authenticators. This tutorial goes through working with the JupyterHub API to manage servers for users.