Provide consistent myst references to documentation pages

While doing jupyterhub#2726, I realized we don't have a consistent way to format references inside the docs. I now have them be formatted to match the name of the file, but using `:` to separate them instead of `/` or `-`. `/` makes it ambiguous when using with markdown link syntax, as it could be a reference or a file. And using `-` is ambiguous, as that can be the name of the file itself. This PR does about half, I can do the other half later (unless someone else does).
yuvipanda · Jun 11, 2024 · 3a9c631 · 3a9c631
1 parent 4c868cd
commit 3a9c631
Show file tree

Hide file tree

Showing 39 changed files with 67 additions and 33 deletions.
diff --git 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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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 <mailto:[email protected]>.
 

diff --git 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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -1,4 +1,4 @@
-(web-security)=
+(explanation:security)=
 
 # Security Overview
 

diff --git 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
@@ -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
@@ -1,4 +1,4 @@
-(troubleshooting)=
+(faq:troubleshooting)=
 
 # Troubleshooting
 

diff --git 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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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.