Revamp our documentation and refactor a bit (#1433)

Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>

Author: choldgraf

.readthedocs.yaml

@@ -6,6 +6,7 @@ version: 2
 
 sphinx:
   configuration: docs/source/conf.py
+  builder: dirhtml
 
 build:
   os: ubuntu-22.04

docs/requirements.txt

@@ -1,7 +1,8 @@
-myst-parser>=0.18
-pydata-sphinx-theme>=0.11
+myst-parser<4
+pydata-sphinx-theme
 sphinx-autobuild
 sphinx-copybutton
+sphinx-design
 sphinxcontrib-autoprogram>=0.1.7
 sphinxext-opengraph
 sphinxext-rediraffe

docs/source/_static/images/logo-dark.png

@@ -20,11 +20,11 @@ with explicit **versions** is all that is needed.
 In repo2docker, a Buildpack does the following things:
 
 1. **Detect** if it can handle a given repository
-2. **Build** a base language environment in the docker image
-3. **Copy** the contents of the repository into the docker image
-4. **Assemble** a specific environment in the docker image based on repository contents
-5. **Push** the built docker image to a specific docker registry (optional)
-6. **Run** the build docker image as a docker container (optional)
+2. **Build** a base language environment in the Docker image
+3. **Copy** the contents of the repository into the Docker image
+4. **Assemble** a specific environment in the Docker image based on repository contents
+5. **Push** the built Docker image to a specific Docker registry (optional)
+6. **Run** the build Docker image as a Docker container (optional)
 
 ### Detect
 
@@ -56,15 +56,15 @@ repositories built with the same buildpack.
 For example, in `CondaBuildPack`, the base environment consists of installing [miniconda](https://conda.io/miniconda.html)
 and basic notebook packages (from `repo2docker/buildpacks/conda/environment.yml`). This is going
 to be the same for most repositories built with `CondaBuildPack`, so we want to use
-[docker layer caching](https://thenewstack.io/understanding-the-docker-cache-for-faster-builds/) as
+[Docker layer caching](https://thenewstack.io/understanding-the-docker-cache-for-faster-builds/) as
 much as possible for performance reasons. Next time a repository is built with `CondaBuildPack`,
-we can skip straight to the **copy** step (since the base environment docker image _layers_ have
+we can skip straight to the **copy** step (since the base environment Docker image _layers_ have
 already been built and cached).
 
 The `get_build_scripts` and `get_build_script_files` methods are primarily used for this.
 `get_build_scripts` can return arbitrary bash script lines that can be run as different users,
 and `get_build_script_files` is used to copy specific scripts (such as a conda installer) into
-the image to be run as pat of `get_build_scripts`. Code in either has following constraints:
+the image to be run as part of `get_build_scripts`. Code in either has following constraints:
 
 1. You can _not_ use the contents of repository in them, since this happens before the repository
    is copied into the image. For example, `pip install -r requirements.txt` will not work,
@@ -91,22 +91,20 @@ This usually means installing required libraries specified in a format native to
 
 Most of this work is done in `get_assemble_scripts` method. It can return arbitrary bash script
 lines that can be run as different users, and has access to the repository contents (unlike
-`get_build_scripts`). The docker image layers produced by this usually can not be cached,
+`get_build_scripts`). The Docker image layers produced by this usually can not be cached,
 so less restrictions apply to this than to `get_build_scripts`.
 
-At the end of the assemble step, the docker image is ready to be used in various ways!
+At the end of the assemble step, the Docker image is ready to be used in various ways!
 
 ### Push
 
-Optionally, repo2docker can **push** a built image to a [docker registry](https://docs.docker.com/registry/),
+Optionally, repo2docker can **push** a built image to a [Docker registry](https://docs.docker.com/registry/),
 if you specify the `--push` flag.
 
 ### Run
 
-Optionally, repo2docker can **run** the built image and allow the user to access the Jupyter Notebook
-running inside by default. This is also done as a convenience only (since you can do the same with `docker run`
-after using repo2docker only to build), and implemented in `Repo2Docker.run`. It is activated by default
-unless the `--no-run` commandline flag is passed.
+Optionally, repo2docker can **run** the built image and allow the user to access the Jupyter Notebook running inside by default.
+This is also done as a convenience only (since you can do the same with `docker run` after using repo2docker only to build), and implemented in `Repo2Docker.run`. It is activated by default unless the `--no-run` commandline flag is passed.
 
 ## ContentProviders
 

docs/source/_static/images/logo.png

@@ -134,7 +134,7 @@
 - pre-commit update to fix ci [#1238](https://github.com/jupyterhub/repo2docker/pull/1238) ([@minrk](https://github.com/minrk))
 - Upgrade to mamba 1.1 and enable rich SAT error messages [#1232](https://github.com/jupyterhub/repo2docker/pull/1232) ([@SylvainCorlay](https://github.com/SylvainCorlay))
 - Upgrade to mamba 1.0 [#1213](https://github.com/jupyterhub/repo2docker/pull/1213) ([@SylvainCorlay](https://github.com/SylvainCorlay))
-- docker image: update alpine to 3.16 [#1212](https://github.com/jupyterhub/repo2docker/pull/1212) ([@consideRatio](https://github.com/consideRatio))
+- Docker image: update alpine to 3.16 [#1212](https://github.com/jupyterhub/repo2docker/pull/1212) ([@consideRatio](https://github.com/consideRatio))
 - reconcile CLI/config priority [#1211](https://github.com/jupyterhub/repo2docker/pull/1211) ([@minrk](https://github.com/minrk))
 - pipfile: pass --clear flag, and do it separetely to not be ignored [#1208](https://github.com/jupyterhub/repo2docker/pull/1208) ([@consideRatio](https://github.com/consideRatio))
 - run submodule test over https [#1204](https://github.com/jupyterhub/repo2docker/pull/1204) ([@minrk](https://github.com/minrk))
@@ -299,12 +299,12 @@ The repo2docker container image has moved to [quay.io/jupyterhub/repo2docker](ht
 
 - Workaround docker-py dependency's failure to import six {pr}`1066:` by {user}`consideratio`
 - fix: add chardet, a not explicitly declared dependency {pr}`1064` by {user}`johnhoman`
-- Add build-base to build stage of docker image {pr}`1051` by {user}`yuvipanda`
+- Add build-base to build stage of Docker image {pr}`1051` by {user}`yuvipanda`
 - Fix regression in hydroshare introduced after moving to requests {pr}`1034` by {user}`MridulS`
 
 ### Other merged PRs
 
-- Update README quay.io URL, Add docker latest tag {pr}`1075` by {user}`manics`
+- Update README quay.io URL, add Docker latest tag {pr}`1075` by {user}`manics`
 - GitHub workflow build and push to Docker hub {pr}`1071` by {user}`manics`
 - Rename master branch to main {pr}`1068` by {user}`manics`
 - Remove Pipfile & Pipfile.lock {pr}`1054` by {user}`yuvipanda`
@@ -343,7 +343,7 @@ The repo2docker container image has moved to [quay.io/jupyterhub/repo2docker](ht
 ### Other merged PRs
 
 - Cleanup install_requires including duplicates {pr}`1020` by {user}`manics`
-- bump docker action version {pr}`1018` by {user}`minrk`
+- bump Docker action version {pr}`1018` by {user}`minrk`
 - bump python in circleci test {pr}`1013` by {user}`minrk`
 - Investigating the missing logs {pr}`1008` by {user}`betatim`
 - Experiment with different install mechanism to get code coverage stats again {pr}`982` by {user}`betatim`
@@ -376,7 +376,7 @@ The repo2docker container image has moved to [quay.io/jupyterhub/repo2docker](ht
 - chmod start script from repo2docker-entrypoint {pr}`886` by {user}`danlester`
 - pypi jupyter-offlinenotebook==0.1.0 {pr}`880` by {user}`manics`
 - Add support for Julia 1.4.1 {pr}`878` by {user}`davidanthoff`
-- Change --env option to work like docker's {pr}`874` by {user}`hwine`
+- Change --env option to work like Docker's {pr}`874` by {user}`hwine`
 - Add support for Julia 1.4.0 {pr}`870` by {user}`davidanthoff`
 - Update server proxy and rsession proxy {pr}`869` by {user}`betatim`
 - Use miniforge instead of miniconda to get conda {pr}`859` by {user}`yuvipanda`
@@ -549,7 +549,7 @@ Release date: 2019-02-21
 
 ### New features
 
-- Add additional metadata to docker images about how they were built {pr}`500` by
+- Add additional metadata to Docker images about how they were built {pr}`500` by
   {user}`jrbourbeau`.
 - Allow users to install global NPM packages: {pr}`573` by {user}`GladysNalvarte`.
 - Add documentation on switching the user interface presented by a
@@ -579,7 +579,7 @@ Release date: 2019-02-21
 - Fix quoting issue in `GIT_CREDENTIAL_ENV` environment variable by
   {user}`minrk` in {pr}`572`.
 - Change to using the first 8 characters of each Git commit, not the last 8,
-  to tag each built docker image of repo2docker itself. {user}`minrk` in {pr}`562`.
+  to tag each built Docker image of repo2docker itself. {user}`minrk` in {pr}`562`.
 - Allow users to select the Julia when using a `requirements.txt` by
   {user}`yuvipanda` in {pr}`557`.
 - Set `JULIA_DEPOT_PATH` to install packages outside the home directory by

docs/source/_static/images/whentouse.svg

@@ -0,0 +1,87 @@
+# Command-line usage and API
+
+`repo2docker` is called with this command:
+
+```
+jupyter-repo2docker <source-repository>
+```
+
+where `<source-repository>` is a repository in one of [the supported repository providers](#repository-providers).
+
+For example, the following command will build an image of Peter Norvig's
+[Pytudes] repository:
+
+```
+jupyter-repo2docker https://github.com/norvig/pytudes
+```
+
+Building the image may take a few minutes.
+
+[Pytudes] uses a [`requirements.txt` file](https://github.com/norvig/pytudes/blob/HEAD/requirements.txt) to specify its Python environment. Because of this, `repo2docker` will use `pip` to install dependencies listed in this `requirements.txt` file, and these will be present in the generated Docker image. To learn more about configuration files in `repo2docker` visit [](#config-files).
+
+When the image is built, a message will be output to your terminal:
+
+```
+Copy/paste this URL into your browser when you connect for the first time,
+to login with a token:
+    http://0.0.0.0:36511/?token=f94f8fabb92e22f5bfab116c382b4707fc2cade56ad1ace0
+```
+
+Pasting the URL into your browser will open Jupyter Notebook with the
+dependencies and contents of the source repository in the built image.
+
+## Debug repo2docker with `--debug` and `--no-build`
+
+To debug the container image being built, pass the `--debug` parameter:
+
+> ```bash
+> jupyter-repo2docker --debug https://github.com/norvig/pytudes
+> ```
+
+This will print the generated `Dockerfile`, build it, and run it.
+
+To see the generated `Dockerfile` without actually building it, pass `--no-build` to the commandline.
+This `Dockerfile` output is for **debugging purposes** of `repo2docker` only - it can not be used by Docker directly.
+
+> ```bash
+> jupyter-repo2docker --no-build --debug https://github.com/norvig/pytudes
+> ```
+
+## Build from a branch, commit or tag
+
+To build a particular branch and commit, use the argument `--ref` and
+specify the `branch-name` or `commit-hash`. For example:
+
+```
+jupyter-repo2docker --ref 9ced85dd9a84859d0767369e58f33912a214a3cf https://github.com/norvig/pytudes
+```
+
+:::{tip}
+For reproducible builds, we recommend specifying a commit-hash to
+deterministically build a fixed version of a repository. Not specifying a
+commit-hash will result in the latest commit of the repository being built.
+:::
+
+## Set environment variables during builds
+
+When running repo2docker locally you can use the `-e` or `--env` command-line
+flag for each variable that you want to define.
+
+For example:
+
+```bash
+jupyter-repo2docker -e VAR1=val1 -e VAR2=val2 ...
+```
+
+You can also configure environment variables for all users of a repository using the
+[](#config-start) configuration file.
+
+(command-line-api)=
+
+## Command-line API
+
+```{autoprogram} repo2docker.__main__:argparser
+:prog: jupyter-repo2docker
+```
+
+[pytudes]: https://github.com/norvig/pytudes

docs/source/architecture.md

@@ -22,6 +22,7 @@
     "sphinxcontrib.autoprogram",
     "sphinxext.opengraph",
     "sphinxext.rediraffe",
+    "sphinx_design",
 ]
 root_doc = "index"
 source_suffix = [".md", ".rst"]
@@ -40,6 +41,7 @@
 #
 myst_enable_extensions = [
     "colon_fence",
+    "substitution",
 ]
 
 
@@ -58,8 +60,11 @@
 
 from repo2docker.buildpacks.conda import CondaBuildPack
 
-default_python = CondaBuildPack.major_pythons["3"]
-
+default_python = f"`Python {CondaBuildPack.major_pythons['3']}`"
+myst_substitutions = {
+    "default_python": default_python,
+    "default_python_version": default_python,
+}
 rst_prolog = f"""
 .. |default_python| replace:: **Python {default_python}**
 .. |default_python_version| replace:: {default_python}
@@ -73,12 +78,20 @@
 html_favicon = "_static/images/favicon.ico"
 html_static_path = ["_static"]
 html_css_files = ["custom.css"]
+html_sidebars = {
+    "changelog": [],
+    "start": [],
+}
 
 # pydata_sphinx_theme reference: https://pydata-sphinx-theme.readthedocs.io/en/latest/
 html_theme = "pydata_sphinx_theme"
 html_theme_options = {
     "use_edit_page_button": True,
     "github_url": "https://github.com/jupyterhub/repo2docker",
+    "logo": {
+        "image_dark": "_static/images/logo-dark.png",
+        "image_light": "_static/images/logo.png",
+    },
 }
 html_context = {
     "github_user": "jupyterhub",