Create a separate doc page on how to build a custom set of images

docs/contributing/features.md

@@ -12,6 +12,7 @@ Please follow the process below to suggest a new feature for inclusion in one of
    describing the feature you'd like to contribute.
 2. Discuss with the maintainers whether the addition makes sense
    in [one of the core stacks](../using/selecting.md#core-stacks),
+   as a [way to build a custom set of images](../using/custom-images.md),
    as a [recipe in the documentation](recipes.md),
    as a [community stack](stacks.md),
    or as something else entirely.

docs/index.rst

@@ -13,6 +13,7 @@ Table of Contents
    using/common
    using/specifics
    using/recipes
+   using/custom-images
    using/troubleshooting
    using/faq
 

docs/using/custom-images.md

@@ -0,0 +1,82 @@
+# Building a custom set of images
+
+This section describes how to build a custom set of images.
+It may be helpful if you need to change the Ubuntu or Python version, or to make a significant change to the build process itself.
+
+This project only builds one set of images at a time.
+If you want to use older images, take a look [here](https://jupyter-docker-stacks.readthedocs.io/en/latest/#using-old-images).
+
+## Automating your build using template cookiecutter project
+
+If you wish to build your own image on top of one of our images and automate your build process,
+please, [take a look at cookiecutter template](../contributing/stacks.md).
+
+## Custom arguments
+
+Existing customization points:
+
+- `ROOT_CONTAINER` - a docker argument of `docker-stacks-foundation` image
+- `PYTHON_VERSION` - a docker argument of `docker-stacks-foundation` image
+- `REGISTRY`, `OWNER`, `BASE_CONTAINER` - docker arguments for all the other images we build
+- `REGISTRY`, `OWNER` - part of `env` in most of our GitHub workflows
+
+## Building stack images with custom arguments
+
+A selection of prebuilt images are available from [Quay.io](https://quay.io/organization/jupyter),
+however, it's impossible to cater to everybody's needs.
+For extensive customization with an automated build pipeline,
+you may wish to create a [community-maintained stack](../contributing/stacks),
+however, for minor customizations, this may be overkill.
+For example, you may wish to use the same Jupyter stacks but built on a different base image,
+or built with a different Python version.
+
+To achieve this you can use [Docker Bake](https://docs.docker.com/build/bake/)
+to build the stacks locally with custom arguments.
+
+```{note}
+Custom arguments may result in build errors due to incompatibility.
+If so your use-case may require a fully customized stack.
+```
+
+As a basic example, if you want to build a custom image based on the `minimal-notebook` image using `Python 3.12`,
+then with a Dockerfile like:
+
+```{code-block} Dockerfile
+:caption: Dockerfile
+
+ARG BASE_CONTAINER=minimal-notebook
+FROM $BASE_CONTAINER
+...
+```
+
+Include the below file in your project:
+
+```{literalinclude} recipe_code/docker-bake.python312.hcl
+:force:
+:language: hcl
+:caption: docker-bake.hcl
+```
+
+To build this stack, in the same directory run:
+
+```bash
+docker buildx bake
+```
+
+Docker Bake then determines the correct build order from the `contexts` parameters
+and builds the stack as requested.
+
+This image can then be run the same way as any other image provided by this project, for example:
+
+```bash
+docker run -it --rm -p 8888:8888 custom-jupyter
+```
+
+or referenced in a Docker Compose file.
+
+## Forking our repository
+
+If for some reason, you need to change more things in our images, feel free to fork it and change it any way you want.
+If your customization is easy to backport to the main repo and might be helpful for other users, feel free to create a PR.
+
+It is almost always a great idea to keep your diff as small as possible and to merge/rebase the latest version of our repo in your project.

docs/using/recipes.md

@@ -4,6 +4,9 @@ Users sometimes share interesting ways of using the Jupyter Docker Stacks.
 We encourage users to [contribute these recipes](../contributing/recipes.md) to the documentation in case they prove helpful to other community members by submitting a pull request to `docs/using/recipes.md`.
 The sections below capture this knowledge.
 
+All the recipes here assume you would like to use an image built by this project and install some things on top of it.
+If you would like to build a custom set of images, [take a look at the docs](custom-images.md).
+
 ## Using `sudo` within a container
 
 Password authentication is disabled for the `NB_USER` (e.g., `jovyan`).
@@ -517,57 +520,3 @@ they may be explained in the "Installation instructions" section of the Download
 ```{literalinclude} recipe_code/oracledb.dockerfile
 :language: docker
 ```
-
-## Building stack images with custom arguments
-
-A selection of prebuilt images are available from Quay.io,
-however, it's impossible to cater to everybody's needs.
-For extensive customization with an automated build pipeline,
-you may wish to create a [community-maintained stack](https://jupyter-docker-stacks.readthedocs.io/en/latest/contributing/stacks.html),
-however, for minor customizations, this may be overkill.
-For example, you may wish to use the same jupyter stacks but built on a different base image,
-or build with a different Python version.
-
-To achieve this you can use [Docker Bake](https://docs.docker.com/build/bake/)
-to build the stacks locally with custom arguments.
-
-```{note}
-Custom arguments may result in build errors due to incompatibility.
-If so your use-case may require a fully customized stack.
-```
-
-As a basic example, if you want to build a custom image based on the `minimal-notebook` image using `Python 3.12`,
-then with a Dockerfile like:
-
-```{code-block} Dockerfile
-:caption: Dockerfile
-
-ARG BASE_CONTAINER=minimal-notebook
-FROM $BASE_CONTAINER
-...
-```
-
-Include the below file in your project:
-
-```{literalinclude} recipe_code/docker-bake.python312.hcl
-:force:
-:language: hcl
-:caption: docker-bake.hcl
-```
-
-To build this stack, in the same directory run:
-
-```bash
-docker buildx bake
-```
-
-Docker Bake then determines the correct build order from the `contexts` parameters
-and builds the stack as requested.
-
-This image can then be run using:
-
-```bash
-docker run custom-jupyter
-```
-
-or referenced in a docker compose file.