From fc542dae88ef60e468d2e9e128d812e74770f43d Mon Sep 17 00:00:00 2001 From: Ayaz Salikhov Date: Mon, 24 Feb 2025 16:59:47 +0000 Subject: [PATCH] Fix some minor issues in docs --- docs/contributing/features.md | 2 +- docs/contributing/issues.md | 2 +- docs/contributing/lint.md | 6 +++--- docs/contributing/packages.md | 4 ++-- docs/contributing/recipes.md | 2 +- docs/contributing/stacks.md | 6 +++--- docs/using/common.md | 10 +++++----- docs/using/faq.md | 4 ++-- docs/using/recipes.md | 4 ++-- docs/using/selecting.md | 2 +- docs/using/troubleshooting.md | 6 +++--- 11 files changed, 24 insertions(+), 24 deletions(-) diff --git a/docs/contributing/features.md b/docs/contributing/features.md index 7da372de..2ffc9e07 100644 --- a/docs/contributing/features.md +++ b/docs/contributing/features.md @@ -53,6 +53,6 @@ If there's agreement that the feature belongs in one or more of the core stacks: make build/ ``` -3. [Submit a pull request](https://github.com/PointCloudLibrary/pcl/wiki/A-step-by-step-guide-on-preparing-and-submitting-a-pull-request)(PR) with your changes. +3. [Submit a pull request](https://github.com/PointCloudLibrary/pcl/wiki/A-step-by-step-guide-on-preparing-and-submitting-a-pull-request) (PR) with your changes. 4. Watch for GitHub to report a build success or failure for your PR on GitHub. 5. Discuss changes with the maintainers and address any build issues. diff --git a/docs/contributing/issues.md b/docs/contributing/issues.md index 680d584b..dd011600 100644 --- a/docs/contributing/issues.md +++ b/docs/contributing/issues.md @@ -1,6 +1,6 @@ # Project Issues -We appreciate your taking the time to report an issue you encountered using the Jupyter Docker Stacks. +We appreciate you taking the time to report an issue you encountered while using the Jupyter Docker Stacks. Please review the following guidelines when reporting your problem. - If you believe you've found a security vulnerability in any of the Jupyter projects included in Jupyter Docker Stacks images, diff --git a/docs/contributing/lint.md b/docs/contributing/lint.md index 350f07dd..f4fd242a 100644 --- a/docs/contributing/lint.md +++ b/docs/contributing/lint.md @@ -27,10 +27,10 @@ pre-commit install ### Run Now, _pre-commit_ (and so configured hooks) will run automatically on `git commit` on each changed file. -However, it is also possible to trigger it against all files. +However, you can also run it against all files manually. ```{note} -Hadolint pre-commit uses Docker to run, so `docker` should be running while running this command. +Hadolint pre-commit uses Docker to run, so `docker` should be running while executing this command. ``` ```sh @@ -58,7 +58,7 @@ The following rules are ignored by default for all images in the `.hadolint.yaml - [`DL3008`][dl3008]: System packages are always updated (`apt-get`) to the latest version. - [`DL3013`][dl3013]: We always install the latest packages using `pip` -The preferred way to do it for other rules is to flag ignored ones in the `Dockerfile`. +The preferred way to ignore other rules is to flag them in the `Dockerfile`. > It is also possible to ignore rules by using a special comment directly above the Dockerfile instruction you want to make an exception for. > Ignore rule comments look like `# hadolint ignore=DL3001,SC1081`. diff --git a/docs/contributing/packages.md b/docs/contributing/packages.md index d6b77060..c93cf4d6 100644 --- a/docs/contributing/packages.md +++ b/docs/contributing/packages.md @@ -12,8 +12,8 @@ We pin major.minor version of Python, so this will stay the same even after invo ## Outdated packages To help identify packages that can be updated, you can use the following helper tool. -It will list all the outdated packages installed in the `Dockerfile` -- -dependencies are filtered to focus only on requested packages. +It will list all the outdated packages installed in the `Dockerfile`. +Dependencies are filtered to display only the requested packages. ```bash make check-outdated/base-notebook diff --git a/docs/contributing/recipes.md b/docs/contributing/recipes.md index 45afb60c..ee981834 100644 --- a/docs/contributing/recipes.md +++ b/docs/contributing/recipes.md @@ -1,6 +1,6 @@ # New Recipes -We welcome contributions of [recipes](../using/recipes.md), and short examples of using, configuring, or extending the Docker Stacks for inclusion in the documentation site. +We welcome contributions of [recipes](../using/recipes.md), which are short examples of using, configuring, or extending the Docker Stacks for inclusion in the documentation site. Follow the process below to add a new recipe: 1. Open the `docs/using/recipes.md` source file. diff --git a/docs/contributing/stacks.md b/docs/contributing/stacks.md index 37b474e6..ebf238b5 100644 --- a/docs/contributing/stacks.md +++ b/docs/contributing/stacks.md @@ -35,8 +35,8 @@ This will serve as both the git repository name and the part of the Docker image stack_name [my-jupyter-stack]: ``` -Enter the user or organization name under which this stack will reside on Quay.io. -You must have access to manage this Quay.io organization to push images here. +Enter the user or organization name under which this stack will reside on Docker Hub. +You must have access to manage this Docker Hub organization to push images here. ```text stack_org [my-project]: @@ -150,5 +150,5 @@ Finally, if you'd like to add a link to your project to this documentation site, 1. Fork the [jupyter/docker-stacks](https://github.com/jupyter/docker-stacks) GitHub repository. 2. Open the `docs/using/selecting.md` source file and locate the **Community Stacks** section in your fork. 3. Add a table entry with a link to your project, a binder link, and a short description of what your Docker image contains. -4. [Submit a pull request](https://github.com/PointCloudLibrary/pcl/wiki/A-step-by-step-guide-on-preparing-and-submitting-a-pull-request)(PR) with your changes. +4. [Submit a pull request](https://github.com/PointCloudLibrary/pcl/wiki/A-step-by-step-guide-on-preparing-and-submitting-a-pull-request) (PR) with your changes. Maintainers will respond and work with you to address any formatting or content issues. diff --git a/docs/using/common.md b/docs/using/common.md index 64a48eac..8eb6d385 100644 --- a/docs/using/common.md +++ b/docs/using/common.md @@ -35,7 +35,7 @@ You do so by passing arguments to the `docker run` command. - `-e NB_USER=` - The desired username and associated home folder. The default value is `jovyan`. - Setting `NB_USER` refits the `jovyan` default user and ensures that the desired user has the correct file permissions + Setting `NB_USER` redefines the `jovyan` default user and ensures that the desired user has the correct file permissions for the new home directory created at `/home/`. For this option to take effect, you **must** run the container with `--user root`, set the working directory `-w "/home/"` and set the environment variable `-e CHOWN_HOME=yes`. @@ -90,7 +90,7 @@ You do so by passing arguments to the `docker run` command. While the default `umask` value should be sufficient for most use cases, you can set the `NB_UMASK` value to fit your requirements. ```{note} - `NB_UMASK` when set only applies to the Jupyter process itself - + When `NB_UMASK` is set, it only applies to the Jupyter process itself - you cannot use it to set a `umask` for additional files created during `run-hooks.sh`. For example, via `pip` or `conda`. If you need to set a `umask` for these, you **must** set the `umask` value for each command. @@ -122,7 +122,7 @@ You do so by passing arguments to the `docker run` command. - `-e RESTARTABLE=yes` - Runs Jupyter in a loop so that quitting Jupyter does not cause the container to exit. This may be useful when installing extensions that require restarting Jupyter. - `-v /some/host/folder/for/work:/home/jovyan/work` - Mounts a host machine directory as a folder in the container. - This configuration is useful for preserving notebooks and other work even after the container is destroyed. + This configuration is useful for preserving notebooks and other work even after the container has been destroyed. **You must grant the within-container notebook user or group (`NB_UID` or `NB_GID`) write access to the host directory (e.g., `sudo chown 1000 /some/host/folder/for/work`).** - `-e JUPYTER_ENV_VARS_TO_UNSET=ADMIN_SECRET_1,ADMIN_SECRET_2` - Unsets specified environment variables in the default startup script. The variables are unset after the hooks have been executed but before the command provided to the startup script runs. @@ -136,7 +136,7 @@ You do so by passing arguments to the `docker run` command. You can further customize the container environment by adding shell scripts (`*.sh`) to be sourced or executables (`chmod +x`) to be run to the paths below: -- `/usr/local/bin/start-notebook.d/` - handled **before** any of the standard options noted above are applied +- `/usr/local/bin/start-notebook.d/` - handled **before** any of the standard options noted above is applied - `/usr/local/bin/before-notebook.d/` - handled **after** all the standard options noted above are applied and ran right before the Server launches @@ -246,7 +246,7 @@ This script is handy when you derive a new Dockerfile from this image and instal The default Python 3.x [Conda environment](https://docs.conda.io/projects/conda/en/latest/user-guide/concepts/environments.html) resides in `/opt/conda`. The `/opt/conda/bin` directory is part of the default `jovyan` user's `${PATH}`. -That directory is also searched for binaries when run using `sudo` (`sudo my_binary` will search for `my_binary` in `/opt/conda/bin/` +That directory is also searched for binaries when run using `sudo` (`sudo my_binary` will search for `my_binary` in `/opt/conda/bin/`). The `jovyan` user has full read/write access to the `/opt/conda` directory. You can use either `mamba`, `pip`, or `conda` (`mamba` is recommended) to install new packages without any additional permissions. diff --git a/docs/using/faq.md b/docs/using/faq.md index 7f45d73e..0df45a63 100644 --- a/docs/using/faq.md +++ b/docs/using/faq.md @@ -2,7 +2,7 @@ ## How to persist user data -There are 2 types of data, which you might want to persist. +There are two types of data, which you might want to persist. 1. If you want to persist your environment (i.e. packages installed by `mamba`, `conda`, `pip`, `apt-get`, and so on), then you should create an inherited image and install packages only once while building your Dockerfile. @@ -22,7 +22,7 @@ There are 2 types of data, which you might want to persist. You can find [an example of using a bind mount here](./running.md#example-2). There is also [a mount troubleshooting section](./troubleshooting.md#permission-denied-when-mounting-volumes) if you experience any issues. -## Why we do not add your favorite package +## Why we don't add your favorite package We have lots of users with different packages they want to use. Adding them all is impossible, so we have several images to choose from. diff --git a/docs/using/recipes.md b/docs/using/recipes.md index 76cb1dea..e30ca55f 100644 --- a/docs/using/recipes.md +++ b/docs/using/recipes.md @@ -60,7 +60,7 @@ docker run -it --rm \ The default version of `Python` that ships with the image may not be the version you want. The instructions below permit adding a conda environment with a different `Python` version and making it accessible to Jupyter. You may also use older images like `jupyter/base-notebook:python-3.10`. -A list of all tags can be found [here](https://github.com/jupyter/docker-stacks/wiki) +A list of all tags can be found [here](https://github.com/jupyter/docker-stacks/wiki). ```{literalinclude} recipe_code/custom_environment.dockerfile :language: docker @@ -400,7 +400,7 @@ docker run -it --rm \ ## Enable nbclassic-extension spellchecker for markdown (or any other nbclassic-extension) ```{note} -This recipe only works for NBCassic with Jupyter Notebook < 7. +This recipe only works for NBClassic with Jupyter Notebook < 7. It is recommended to use [jupyterlab-spellchecker](https://github.com/jupyterlab-contrib/spellchecker) in modern environments. ``` diff --git a/docs/using/selecting.md b/docs/using/selecting.md index d02e1624..fc9b2c26 100644 --- a/docs/using/selecting.md +++ b/docs/using/selecting.md @@ -244,7 +244,7 @@ It contains: We provide CUDA accelerated versions of the `pytorch-notebook` and `tensorflow-notebook` images. Prepend a CUDA prefix (versioned prefix like `cuda12-` for `pytorch-notebook` or just `cuda-` for `tensorflow-notebook`) to the image tag to allow PyTorch or TensorFlow operations to use compatible NVIDIA GPUs for accelerated computation. -We only build `pytorch-notebook` for last two major versions of CUDA. +We only build `pytorch-notebook` for the last two major versions of CUDA. The `tensorflow-notebook` image only supports the latest CUDA version listed in the [officially tested build configurations](https://www.tensorflow.org/install/source#gpu). For example, you could use the image `quay.io/jupyter/pytorch-notebook:cuda12-python-3.11.8` or `quay.io/jupyter/tensorflow-notebook:cuda-latest`. diff --git a/docs/using/troubleshooting.md b/docs/using/troubleshooting.md index f06577e5..3d10b95c 100644 --- a/docs/using/troubleshooting.md +++ b/docs/using/troubleshooting.md @@ -77,7 +77,7 @@ The following sections cover a few of these scenarios and how to fix them. - If you are mounting your volume inside the `/home/` directory, you can use the `-e CHOWN_HOME=yes` and `CHOWN_HOME_OPTS="-R"` flags instead of the `-e CHOWN_EXTRA` and `-e CHOWN_EXTRA_OPTS` in the example above. - This solution should work in most cases where you have created a docker volume - (i.e. using the [`docker volume create --name `command](https://docs.docker.com/engine/storage/volumes/#create-and-manage-volumes)) and mounted it using the `-v` flag in `docker run`. + (i.e. using the [`docker volume create --name ` command](https://docs.docker.com/engine/storage/volumes/#create-and-manage-volumes)) and mounted it using the `-v` flag in `docker run`. ``` 2. **Matching the container's UID/GID with the host's** @@ -108,7 +108,7 @@ The following sections cover a few of these scenarios and how to fix them. where: - - `NB_IUD` and `NB_GID` should match the local user's UID and GID. + - `NB_UID` and `NB_GID` should match the local user's UID and GID. - You **must** use `--user root` to ensure that the `UID` and `GID` are updated at runtime. ````{admonition} Additional notes @@ -273,7 +273,7 @@ conda config --show default_channels You can install packages from other conda channels (e.g. `bioconda`) by disabling the `channel_priority` setting: ```bash -# install by disabling channel priority at еру command level +# install by disabling channel priority at the command level conda install --no-channel-priority -c bioconda bioconductor-geoquery ```