Merge pull request #1442 from rgaiacs/improve-documentation

Minor improvements to documentation

Author: manics

docs/source/conf.py

@@ -60,7 +60,7 @@
 
 from repo2docker.buildpacks.conda import CondaBuildPack
 
-default_python = f"`Python {CondaBuildPack.major_pythons['3']}`"
+default_python = f"Python {CondaBuildPack.major_pythons['3']}"
 myst_substitutions = {
     "default_python": default_python,
     "default_python_version": default_python,

docs/source/configuration/development.md

@@ -21,7 +21,7 @@ both kinds.
 
 This specifies a list of Python packages that should be installed in your
 environment. Our
-[requirements.txt example](https://github.com/binder-examples/requirements/blob/HEAD/requirements.txt)
+[example `requirements.txt` file](https://github.com/binder-examples/requirements/blob/HEAD/requirements.txt)
 on GitHub shows a typical requirements file.
 
 (setup-py)=

docs/source/configuration/index.md

@@ -1,6 +1,6 @@
 (config-files)=
 
-# Configuration files supported by repo2docker
+# Configuration files supported by `repo2docker`
 
 `repo2docker` looks for configuration files in the repository being built
 to determine how to build it. In general, `repo2docker` uses the same
@@ -15,7 +15,7 @@ Python and R installation in a repository.
 :::
 
 A list of supported configuration files (roughly in the order of build priority)
-can be found on this page (and to the right).
+can be found in the next sections.
 
 ```{toctree}
 :maxdepth: 2

docs/source/configuration/research.md

@@ -8,18 +8,18 @@
 that lets you install any kind of package,
 including Python, R, and C/C++ packages.
 `repo2docker` does not use your `environment.yml` to create and activate a new conda environment.
-Rather, it updates a base conda environment [defined here](https://github.com/jupyterhub/repo2docker/blob/HEAD/repo2docker/buildpacks/conda/environment.yml) with the packages listed in your `environment.yml`.
+Rather, it updates a [pre-defined base conda environment](https://github.com/jupyterhub/repo2docker/blob/HEAD/repo2docker/buildpacks/conda/environment.yml) with the packages listed in your `environment.yml`.
 This means that the environment will always have the same default name, not the name
 specified in your `environment.yml`.
 
 :::{note}
-You can install files from pip in your `environment.yml` as well.
-For example, see the [binder-examples environment.yml](https://github.com/binder-examples/python-conda_pip/blob/HEAD/environment.yml) file. See [the `conda` environment management instructions](https://docs.conda.io/projects/conda/en/latest/user-guide/tasks/manage-environments.html#creating-an-environment-file-manually) for more information.
+You can install files from [PyPI](https://pypi.org/) in your `environment.yml` as well.
+For example, see the [example `environment.yml` file](https://github.com/binder-examples/python-conda_pip/blob/HEAD/environment.yml) file. See [the `conda` environment management instructions](https://docs.conda.io/projects/conda/en/latest/user-guide/tasks/manage-environments.html#creating-an-environment-file-manually) for more information.
 :::
 
 You can also specify which Python version to install in your built environment with `environment.yml`.
 By default, `repo2docker` installs {{ default_python }} with your `environment.yml` unless you include the version of Python in the `environment.yml` of your Git repository.
-`conda` should support all versions of Python, though `repo2docker` support is best with `Python 3.7-3.11`.
+`conda` should support all versions of Python, though `repo2docker` support is best with Python 3.7-3.11.
 
 :::{warning}
 If you include a Python version in a `runtime.txt` file in addition to your
@@ -28,7 +28,7 @@ If you include a Python version in a `runtime.txt` file in addition to your
 
 (install-r)=
 
-## `install.R` - Install packages with R/RStudio
+## `install.R` - Install R packages
 
 This is used to install R libraries pinned to a specific snapshot on
 [Posit Package Manager](https://packagemanager.posit.co/).
@@ -38,7 +38,7 @@ To set the date of the snapshot, or to specify a specific version of R, add a [r
 
 (description)=
 
-## `DESCRIPTION` - Install an R package
+## `DESCRIPTION` - Install as an R package
 
 To install your repository like an R package, you may include a `DESCRIPTION` file.
 `repo2docker` installs the package and dependencies from the `DESCRIPTION` by running `devtools::install_local(getwd())`.

docs/source/configuration/system.md

@@ -2,20 +2,23 @@
 
 (apt-txt)=
 
-## `apt.txt` - Install packages with apt-get
+## `apt.txt` - Install packages with `apt-get`
 
-A list of Debian packages that should be installed. The base image used is usually the latest released
-version of Ubuntu.
+A list of packages in the [`.deb`](<https://en.wikipedia.org/wiki/Deb_(file_format)>) format that should be installed. The `.deb` files are downloaded from the server configured in the Docker base image.
+
+```{note}
+If a `Dockerfile` is not used to change the Docker base image, the base image  is [Ubuntu](https://ubuntu.com/) [22.04 LTS (Jammy Jellyfish)](https://releases.ubuntu.com/jammy/). All `.deb` files availables are listed in [Ubuntu Packages](https://packages.ubuntu.com/jammy/).
+```
 
 We use `apt.txt`, for example, to install LaTeX in our
-[example apt.txt for LaTeX](https://github.com/binder-examples/latex/blob/HEAD/apt.txt).
+[example `apt.txt` file for LaTeX](https://github.com/binder-examples/latex/blob/HEAD/apt.txt).
 
 (runtime-txt)=
 
 ## `runtime.txt` - Specifying runtimes
 
 Sometimes you want to specify the version of the runtime (e.g. the version of Python or R), but the environment specification format will not let you specify this information (e.g. `requirements.txt` or `install.R`).
-For these cases, we have a special file, `runtime.txt`.
+For these cases, we have a special `runtime.txt` file.
 
 :::{warning}
 `runtime.txt` is only supported when used with environment specifications
@@ -25,23 +28,34 @@ that do not already support specifying the runtime
 
 ### Set the Python version
 
-Add the line `python-x.y` in `runtime.txt` to run the repository with Python version x.y.
+Add the line `python-x.y` in `runtime.txt` to run the repository with Python version `x.y`.
 See our [Python2 example repository](https://github.com/binder-examples/python2_runtime/blob/HEAD/runtime.txt).
 
 ### Set the R version
 
-Add the line `r-<RVERSION>-<YYYY>-<MM>-<DD>` in `runtime.txt` to run the repository with R version `RVERSION` and libraries from a `YYYY-MM-DD` snapshot of the [Posit Package Manager](https://packagemanager.posit.co/client/#/repos/2/overview).
+Add the line `r-x.y-YYYY-MM-DD` in `runtime.txt` to run the repository with R version `x.y` and libraries from a `YYYY-MM-DD` snapshot of the [Posit Package Manager](https://packagemanager.posit.co/client/#/repos/2/overview).
+
+The version of R, i.e. `x.y`, can be set to
+
+- `4.4`
+- `4.3`
+- `4.2`
+- `4.1`
+- `4.0`
+- `3.6`
+- `3.5`
+- `3.4`
+- `3.3`
 
-`RVERSION` can be set to 3.4, 3.5, 3.6, or to patch releases for the 3.5 and 3.6 series.
 If you do not specify a version, the latest release will be used.
 
 See our [R example repository](https://github.com/binder-examples/r/blob/HEAD/runtime.txt).
 
 (default-nix)=
 
-## `default.nix` - the nix package manager
+## `default.nix` - the `nix` package manager
 
-Specify packages to be installed by the [nix package manager](https://github.com/NixOS/nixpkgs).
+Specify packages to be installed by the [`nix` package manager](https://github.com/NixOS/nixpkgs).
 When you use this config file all other configuration files (like `requirements.txt`)
 that specify packages are ignored. When using `nix` you have to specify all
 packages and dependencies explicitly, including the Jupyter notebook package that
@@ -54,7 +68,7 @@ a `nix` expression written in a `default.nix` file. Make sure to
 to produce a reproducible environment.
 
 To see an example repository visit
-[nix binder example](https://github.com/binder-examples/nix).
+[nix example repository](https://github.com/binder-examples/nix).
 
 (dockerfile)=
 

docs/source/use/index.md

@@ -1,9 +1,9 @@
 # User guide
 
-Short, actionable guides that cover specific topics with repo2docker.
+Short, actionable guides that cover specific topics with `repo2docker`.
 Select from the pages listed below to get started.
 
-Information about configuring your repository to work with repo2docker,
+Information about configuring your repository to work with `repo2docker`,
 and controlling elements of the built environment using configuration files.
 
 ```{toctree}

docs/source/use/pathways.md

@@ -41,21 +41,21 @@ This is not the same thing as forking the repository for the community image, mo
 :::{grid-item-card} Benefits
 
 - Only need to maintain the changes you make
-- Update the FROM tag to keep up with upstream changes
-- You must manage a GH repo
-- Works well with mybinder.org
+- Update the `FROM` tag to keep up with upstream changes
+- You must manage a Git repository
+- Works well with [mybinder.org]
   :::
   :::{grid-item-card} Drawbacks
 - Need to understand how upstream image is built so you can customize
 - Documentation for this method currently sucks (but can be fixed!)
 - Removing existing packages might break things
-- You must manage a GH repo
+- You must manage a Git repository
   :::
   ::::
 
 See [](./extend-community-image.md) for a how-to guide.
 
-## 3. Use repo2docker to build your environment image
+## 3. Use `repo2docker` to build your environment image
 
 If your needs differ far enough from the community-maintained images that you find, you can use `repo2docker` to build your environment image using [supported configuration files](#config-files).
 To learn how to do this, follow the [getting started with repo2docker guide](../start.md) and look at the [list of supported configuration files](#config-files).
@@ -64,7 +64,7 @@ Check out the other sections under "Image building basics" for more useful how-t
 ::::{grid} 2
 :::{grid-item-card} Benefits
 
-- Works well with mybinder.org
+- Works well with [mybinder.org]
 - No need to learn Dockerfile syntax
 - Use language specific, well understood file formats
 - Only get whatever packages you want
@@ -79,7 +79,7 @@ Check out the other sections under "Image building basics" for more useful how-t
 
 ## 4. Use a full fledged custom Dockerfile
 
-If you need full control over the entire computational environment, you can always create your own `Dockerfile` from scratch, and repo2docker will build an image out of it.
+If you need full control over the entire computational environment, you can always create your own `Dockerfile` from scratch, and `repo2docker` will build an image out of it.
 
 This is for advanced users only that know what they're doing - full guidance on how to use `Dockerfiles` is out of scope for this tutorial.
 
@@ -90,13 +90,15 @@ This is for advanced users only that know what they're doing - full guidance on
 
 - Get exactly what you want
 - Can be optimized for small image size & fast build times
-- Lots of existing documentation in the SRE world on how to use these
+- Lots of existing documentation in the site reliability engineer world on how to use these
 
 :::
 :::{grid-item-card} Drawbacks
 
 - Requires a lot of knowledge for ongoing maintenance
 - Might have to solve problems yourself that were solved in upstream images / repo2docker
-- Need to adapt existing documentation from the SRE use case to interactive computing use case
+- Need to adapt existing documentation from the site reliability engineer use case to interactive computing use case
   :::
   ::::
+
+[mybinder.org]: https://mybinder.org