hazza/jupyterhub
1
0
Fork 0
mirror of https://github.com/jupyterhub/jupyterhub.git synced 2025-10-08 18:44:10 +00:00
Code Issues Packages Projects Releases Wiki Activity

Merge pull request #5116 from rgaiacs/improve-documentation-dev

Browse Source 
Collection of small improvements to contributor documentation
This commit is contained in:
Erik Sundell
2025-08-05 16:02:49 +02:00
committed by GitHub
parent 74b5e2601d 3e09b979bc
commit 1b00e49e4d
5 changed files with 22 additions and 22 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
docs/source/contributing/docs.md
View File

@@ -8,7 +8,7 @@ you get set up on how to contribute to JupyterHub's documentation.
## Building documentation locally ## Building documentation locally
We use [sphinx](https://www.sphinx-doc.org) to build our documentation. It takes We use [sphinx](https://www.sphinx-doc.org) to build our documentation. It takes
our documentation source files (written in [markdown](https://daringfireball.net/projects/markdown/) or [reStructuredText](https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html) & our documentation source files (written in [markdown](https://daringfireball.net/projects/markdown/) or [reStructuredText](https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html) and
stored under the `docs/source` directory) and converts it into various stored under the `docs/source` directory) and converts it into various
formats for people to read. To make sure the documentation you write or formats for people to read. To make sure the documentation you write or
change renders correctly, it is good practice to test it locally. change renders correctly, it is good practice to test it locally.

2
docs/source/contributing/index.md
View File

@@ -3,7 +3,7 @@
# Contributing # Contributing
We want you to contribute to JupyterHub in ways that are most exciting We want you to contribute to JupyterHub in ways that are most exciting
and useful to you. We value documentation, testing, bug reporting & code equally, and useful to you. We value documentation, testing, bug reporting and code equally,
and are glad to have your contributions in whatever form you wish. and are glad to have your contributions in whatever form you wish.
Be sure to first check our [Code of Conduct](https://github.com/jupyter/governance/blob/HEAD/conduct/code_of_conduct.md) Be sure to first check our [Code of Conduct](https://github.com/jupyter/governance/blob/HEAD/conduct/code_of_conduct.md)

30
docs/source/contributing/setup.md
View File

@@ -16,23 +16,23 @@ requires you have at least version {{python_min}} installed locally. If you have
installed Python before, the recommended way to install it is to use installed Python before, the recommended way to install it is to use
[Miniforge](https://github.com/conda-forge/miniforge#download). [Miniforge](https://github.com/conda-forge/miniforge#download).
### Install nodejs ### Install NodeJS
[NodeJS {{node_min}}+](https://nodejs.org/en/) is required for building some JavaScript components. Some JavaScript components require you have at least version {{node_min}} of [NodeJS](https://nodejs.org/en/) installed locally.
`configurable-http-proxy`, the default proxy implementation for JupyterHub, is written in Javascript. `configurable-http-proxy`, the default proxy implementation for JupyterHub, is written in JavaScript.
If you have not installed NodeJS before, we recommend installing it in the `miniconda` environment you set up for Python. If you have not installed NodeJS before, we recommend installing it in the `miniconda` environment you set up for Python.
You can do so with `conda install nodejs`. You can do so with `conda install nodejs`.
Many in the Jupyter community use [`nvm`](https://github.com/nvm-sh/nvm) to Many in the Jupyter community use [`nvm`](https://github.com/nvm-sh/nvm) to
managing node dependencies. managing node dependencies.
### Install git ### Install Git
JupyterHub uses [Git](https://git-scm.com) & [GitHub](https://github.com) JupyterHub uses [Git](https://git-scm.com) and [GitHub](https://github.com)
for development & collaboration. You need to [install git](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git) to work on for development and collaboration. You need to [install Git](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git) to work on
JupyterHub. We also recommend getting a free account on GitHub.com. JupyterHub. We also recommend getting a free account on GitHub.
## Setting up a development install ## Install JupyterHub for development
When developing JupyterHub, you would need to make changes and be able to instantly view the results of the changes. To achieve that, a developer install is required. When developing JupyterHub, you would need to make changes and be able to instantly view the results of the changes. To achieve that, a developer install is required.
@@ -44,7 +44,7 @@ be achieved in many ways, for example, `tox`, `conda`, `docker`, etc. See this
a more detailed discussion. a more detailed discussion.
::: :::
1. Clone the [JupyterHub git repository](https://github.com/jupyterhub/jupyterhub) 1. Clone the [JupyterHub Git repository](https://github.com/jupyterhub/jupyterhub)
to your computer. to your computer.
```bash ```bash
@@ -65,7 +65,7 @@ a more detailed discussion.
npm -v npm -v
``` ```
This should return a version number greater than or equal to 5.0. This should return a version number greater than or equal to {{node_min}}.
3. Install `configurable-http-proxy` (required to run and test the default JupyterHub configuration): 3. Install `configurable-http-proxy` (required to run and test the default JupyterHub configuration):
@@ -92,7 +92,7 @@ a more detailed discussion.
4. Install an editable version of JupyterHub and its requirements for 4. Install an editable version of JupyterHub and its requirements for
development and testing. This lets you edit JupyterHub code in a text editor development and testing. This lets you edit JupyterHub code in a text editor
& restart the JupyterHub process to see your code changes immediately. and restart the JupyterHub process to see your code changes immediately.
```bash ```bash
python3 -m pip install --editable ".[test]" python3 -m pip install --editable ".[test]"
@@ -109,7 +109,7 @@ a more detailed discussion.
Happy developing! Happy developing!
## Using DummyAuthenticator & SimpleLocalProcessSpawner ## Using DummyAuthenticator and SimpleLocalProcessSpawner
To simplify testing of JupyterHub, it is helpful to use To simplify testing of JupyterHub, it is helpful to use
{class}`~jupyterhub.auth.DummyAuthenticator` instead of the default JupyterHub {class}`~jupyterhub.auth.DummyAuthenticator` instead of the default JupyterHub
@@ -132,17 +132,17 @@ The test configuration enables a few things to make testing easier:
- disable caching of static files - disable caching of static files
The default JupyterHub [authenticator](PAMAuthenticator) The default JupyterHub [authenticator](PAMAuthenticator)
& [spawner](LocalProcessSpawner) and [spawner](LocalProcessSpawner)
require your system to have user accounts for each user you want to log in to require your system to have user accounts for each user you want to log in to
JupyterHub as. JupyterHub as.
DummyAuthenticator allows you to log in with any username & password, DummyAuthenticator allows you to log in with any username and password,
while SimpleLocalProcessSpawner allows you to start servers without having to while SimpleLocalProcessSpawner allows you to start servers without having to
create a Unix user for each JupyterHub user. Together, these make it create a Unix user for each JupyterHub user. Together, these make it
much easier to test JupyterHub. much easier to test JupyterHub.
Tip: If you are working on parts of JupyterHub that are common to all Tip: If you are working on parts of JupyterHub that are common to all
authenticators & spawners, we recommend using both DummyAuthenticator & authenticators and spawners, we recommend using both DummyAuthenticator and
SimpleLocalProcessSpawner. If you are working on just authenticator-related SimpleLocalProcessSpawner. If you are working on just authenticator-related
parts, use only SimpleLocalProcessSpawner. Similarly, if you are working on parts, use only SimpleLocalProcessSpawner. Similarly, if you are working on
just spawner-related parts, use only DummyAuthenticator. just spawner-related parts, use only DummyAuthenticator.

6
docs/source/howto/upgrading.md
View File

@@ -27,7 +27,7 @@ For specific version migrations:
The [changelog](changelog) contains information on what has The [changelog](changelog) contains information on what has
changed with the new JupyterHub release and any deprecation warnings. changed with the new JupyterHub release and any deprecation warnings.
Read these notes to familiarize yourself with the coming changes. There Read these notes to familiarize yourself with the coming changes. There
might be new releases of the authenticators & spawners you use, so might be new releases of the authenticators and spawners you use, so
read the changelogs for those too! read the changelogs for those too!
## Notify your users ## Notify your users
@@ -41,7 +41,7 @@ If you use a different proxy or run `configurable-http-proxy`
independent of JupyterHub, your users will be able to continue using notebook independent of JupyterHub, your users will be able to continue using notebook
servers they had already launched, but will not be able to launch new servers or sign in. servers they had already launched, but will not be able to launch new servers or sign in.
## Backup database & config ## Backup database and config
Before doing an upgrade, it is critical to back up: Before doing an upgrade, it is critical to back up:
@@ -90,7 +90,7 @@ with:
conda install -c conda-forge jupyterhub==<version> conda install -c conda-forge jupyterhub==<version>
``` ```
You should also check for new releases of the authenticator & spawner you You should also check for new releases of the authenticator and spawner you
are using. You might wish to upgrade those packages, too, along with JupyterHub are using. You might wish to upgrade those packages, too, along with JupyterHub
or upgrade them separately. or upgrade them separately.

4
docs/source/reference/spawners.md
View File

@@ -467,7 +467,7 @@ spawner, does not support limits and guarantees. One of the spawners
that supports limits and guarantees is the that supports limits and guarantees is the
[`systemdspawner`](https://github.com/jupyterhub/systemdspawner). [`systemdspawner`](https://github.com/jupyterhub/systemdspawner).
### Memory Limits & Guarantees ### Memory Limits and Guarantees
`c.Spawner.mem_limit`: A **limit** specifies the _maximum amount of memory_ `c.Spawner.mem_limit`: A **limit** specifies the _maximum amount of memory_
that may be allocated, though there is no promise that the maximum amount will that may be allocated, though there is no promise that the maximum amount will
@@ -487,7 +487,7 @@ available for the single-user notebook server to use. The environment variable
limits and providing these guarantees.** If these values are set to `None`, no limits and providing these guarantees.** If these values are set to `None`, no
limits or guarantees are provided, and no environment values are set. limits or guarantees are provided, and no environment values are set.
### CPU Limits & Guarantees ### CPU Limits and Guarantees
`c.Spawner.cpu_limit`: In supported spawners, you can set `c.Spawner.cpu_limit`: In supported spawners, you can set
`c.Spawner.cpu_limit` to limit the total number of cpu-cores that a `c.Spawner.cpu_limit` to limit the total number of cpu-cores that a