Review "Configuration files supported" page

Author: rgaiacs

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/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,23 @@ 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).
 
-`RVERSION` can be set to 3.4, 3.5, 3.6, or to patch releases for the 3.5 and 3.6 series.
+The version of R, i.e. `x.y`, 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 +57,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)=