diff --git a/docs/source/contributing/docs.md b/docs/source/contributing/docs.md index c2a3b4ac..42afd899 100644 --- a/docs/source/contributing/docs.md +++ b/docs/source/contributing/docs.md @@ -8,7 +8,7 @@ you get set up on how to contribute to JupyterHub's documentation. ## Building documentation locally 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 formats for people to read. To make sure the documentation you write or change renders correctly, it is good practice to test it locally. diff --git a/docs/source/contributing/index.md b/docs/source/contributing/index.md index 3c328718..f2d4e200 100644 --- a/docs/source/contributing/index.md +++ b/docs/source/contributing/index.md @@ -3,7 +3,7 @@ # Contributing 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. Be sure to first check our [Code of Conduct](https://github.com/jupyter/governance/blob/HEAD/conduct/code_of_conduct.md) diff --git a/docs/source/contributing/setup.md b/docs/source/contributing/setup.md index 2f97577d..de4b3522 100644 --- a/docs/source/contributing/setup.md +++ b/docs/source/contributing/setup.md @@ -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 [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. -`configurable-http-proxy`, the default proxy implementation for JupyterHub, is written in Javascript. +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. 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`. Many in the Jupyter community use [`nvm`](https://github.com/nvm-sh/nvm) to managing node dependencies. -### Install git +### Install Git -JupyterHub uses [Git](https://git-scm.com) & [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 -JupyterHub. We also recommend getting a free account on GitHub.com. +JupyterHub uses [Git](https://git-scm.com) and [GitHub](https://github.com) +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. -## 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. @@ -44,7 +44,7 @@ be achieved in many ways, for example, `tox`, `conda`, `docker`, etc. See this 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. ```bash @@ -65,7 +65,7 @@ a more detailed discussion. 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): @@ -92,7 +92,7 @@ a more detailed discussion. 4. Install an editable version of JupyterHub and its requirements for 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 python3 -m pip install --editable ".[test]" @@ -109,7 +109,7 @@ a more detailed discussion. Happy developing! -## Using DummyAuthenticator & SimpleLocalProcessSpawner +## Using DummyAuthenticator and SimpleLocalProcessSpawner To simplify testing of JupyterHub, it is helpful to use {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 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 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 create a Unix user for each JupyterHub user. Together, these make it much easier to test JupyterHub. 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 parts, use only SimpleLocalProcessSpawner. Similarly, if you are working on just spawner-related parts, use only DummyAuthenticator. diff --git a/docs/source/howto/upgrading.md b/docs/source/howto/upgrading.md index 6e07db2c..2332fb9f 100644 --- a/docs/source/howto/upgrading.md +++ b/docs/source/howto/upgrading.md @@ -27,7 +27,7 @@ For specific version migrations: 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 +might be new releases of the authenticators and spawners you use, so read the changelogs for those too! ## 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 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: @@ -90,7 +90,7 @@ with: conda install -c conda-forge jupyterhub== ``` -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 or upgrade them separately. diff --git a/docs/source/reference/spawners.md b/docs/source/reference/spawners.md index 27ae16cd..219f9ba2 100644 --- a/docs/source/reference/spawners.md +++ b/docs/source/reference/spawners.md @@ -467,7 +467,7 @@ spawner, does not support limits and guarantees. One of the spawners that supports limits and guarantees is the [`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_ 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 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` to limit the total number of cpu-cores that a