From 0adfed437bcfba6169b5bd720943ad624d812e39 Mon Sep 17 00:00:00 2001 From: Evert Rol Date: Thu, 4 Oct 2018 11:21:18 +0200 Subject: [PATCH] Change FAQ format to reStructuredText - allows for admonition - fixes reST/Sphinx directive used in Markdown - removes dead link --- docs/source/faq.md | 100 -------------------------------------- docs/source/faq.rst | 115 ++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 115 insertions(+), 100 deletions(-) delete mode 100644 docs/source/faq.md create mode 100644 docs/source/faq.rst diff --git a/docs/source/faq.md b/docs/source/faq.md deleted file mode 100644 index 7c5c7e41..00000000 --- a/docs/source/faq.md +++ /dev/null @@ -1,100 +0,0 @@ -# Frequently Asked Questions (FAQ) - -A collection of frequently asked questions with answers. If you have a question -and have found an answer, send a PR to add it here! - -## How should I specify another version of Python? - -One can specify a Python version in the ``environment.yml`` file of a repository. - -## What versions of Python (or R or Julia...) are supported? - -### Python - -Repo2docker officially supports the following versions of Python (specified in environment.yml or runtime.txt): - -- 3.7 (added in 0.7) -- 3.6 (default) -- 3.5 - -Additional versions may work, as long as the -[base environment](https://github.com/jupyter/repo2docker/blob/master/repo2docker/buildpacks/conda/environment.yml) -can be installed for your version of Python. -The most likely source of incompatibility is if one of the packages -in the base environment is not packaged for your Python, -either because the version of the package is too new and your chosen Python is too old, -or vice versa. - -Additionally, if Python 2.7 is specified, -a separate environment for the kernel will be installed with Python 2. -The notebook server will run in the default Python 3.6 environment. - -### Julia - -The following versions of Julia are supported (specified in REQUIRE): - -- 1.0 (added in 0.7) -- 0.7 (added in 0.7) -- 0.6 (default) - -### R - -Only R 3.4.4 is currently supported, which is installed via `apt` from the -[ubuntu bionic repository](https://packages.ubuntu.com/bionic/r-base). - -## Can I add executable files to the user's PATH? - -Yes! With a :ref:`postBuild` file, you can place any files that should be called -from the command line in the folder ``~/.local/``. This folder will be -available in a user's PATH, and can be run from the command line (or as -a subsequent build step.) - -## How do I set environment variables? - -Use the `-e` or `--env` flag for each variable that you want to define. - -For example `jupyter-repo2docker -e VAR1=val1 -e VAR2=val2 ...` - -## Can I use repo2docker to bootstrap my own Dockerfile? - -No, you can't. - -If you pass the `--debug` flag to `repo2docker`, it outputs the intermediate -Dockerfile that is used to build the docker image. While it is tempting to copy -this as a base for your own Dockerfile, that is not supported & in most cases -will not work. The `--debug` output is just our intermediate generated -Dockerfile, and is meant to be built in -[a very specific way](https://github.com/jupyter/repo2docker/blob/master/repo2docker/detectors.py#L381). -Hence the output of `--debug` can not be built with a normal `docker build -t .` -or similar traditional docker command. - -Check out the [binder-examples](http://github.com/binder-examples/) GitHub -organization for example repositories you can copy & modify for your own use! - -## Can I use repo2docker to edit a local repository within a Docker environment? - -Yes: use the `--editable` or `-E` flag (don't confuse it with the `-e` -flag for environment variables), and run repo2docker on a local -repository: `repo2docker -E my-repository/.`. - -This builds a Docker container from the files in that repository -(using, for example, a `requirements.txt` file or `Dockerfile`), then -runs that container, while connecting the home directory inside the -container to the local repository outside the container. For example, -in case there is a notebook file (`.ipynb`), this will open in a local -webbrowser, and one can edit it and save it. The resulting notebook is -updated in both the Docker container and the local repository. Once -the container is exited, the changed file will still be in the local -repository. - -This allows for easy testing of the container while debugging some -items, as well as using a fully customizable container to edit, for -example, notebooks. - -**note** - -Editable mode is a convenience option that will mount the repository -to container working directory (usually `/home/$USER`). If you need to -mount to a different location in the container, use the `--volumes` -option instead. Similarly, for a fully customized user Dockerfile, -this option is not guaranteed to work. diff --git a/docs/source/faq.rst b/docs/source/faq.rst new file mode 100644 index 00000000..48c55739 --- /dev/null +++ b/docs/source/faq.rst @@ -0,0 +1,115 @@ +.. _faq: + +Frequently Asked Questions (FAQ) +================================ + +A collection of frequently asked questions with answers. If you have a question +and have found an answer, send a PR to add it here! + +How should I specify another version of Python? +----------------------------------------------- + +One can specify a Python version in the ``environment.yml`` file of a repository. + +What versions of Python (or R or Julia...) are supported? +--------------------------------------------------------- + +Python +~~~~~~ + +Repo2docker officially supports the following versions of Python (specified in environment.yml or runtime.txt): + +- 3.7 (added in 0.7) +- 3.6 (default) +- 3.5 + +Additional versions may work, as long as the +`base environment `_ +can be installed for your version of Python. +The most likely source of incompatibility is if one of the packages +in the base environment is not packaged for your Python, +either because the version of the package is too new and your chosen Python is too old, +or vice versa. + +Additionally, if Python 2.7 is specified, +a separate environment for the kernel will be installed with Python 2. +The notebook server will run in the default Python 3.6 environment. + +Julia +~~~~~ + +The following versions of Julia are supported (specified in REQUIRE): + +- 1.0 (added in 0.7) +- 0.7 (added in 0.7) +- 0.6 (default) + +R +~ + +Only R 3.4.4 is currently supported, which is installed via ``apt`` from the +`ubuntu bionic repository `_. + +Can I add executable files to the user's PATH? +---------------------------------------------- + +Yes! With a :ref:`postBuild` file, you can place any files that should be called +from the command line in the folder ``~/.local/``. This folder will be +available in a user's PATH, and can be run from the command line (or as +a subsequent build step.) + +How do I set environment variables? +----------------------------------- + +Use the ``-e`` or ``--env`` flag for each variable that you want to define. + +For example ``jupyter-repo2docker -e VAR1=val1 -e VAR2=val2 ...`` + +Can I use repo2docker to bootstrap my own Dockerfile? +----------------------------------------------------- + +No, you can't. + +If you pass the ``--debug`` flag to ``repo2docker``, it outputs the +intermediate Dockerfile that is used to build the docker image. While +it is tempting to copy this as a base for your own Dockerfile, that is +not supported & in most cases will not work. The ``--debug`` output is +just our intermediate generated Dockerfile, and is meant to be built +in a very specific way. Hence the output of ``--debug`` can not be +built with a normal ``docker build -t .`` or similar traditional +docker command. + +Check out the `binder-examples `_ GitHub +organization for example repositories you can copy & modify for your own use! + +Can I use repo2docker to edit a local host repository within a Docker environment? +---------------------------------------------------------------------------------- + +Yes: use the ``--editable`` or ``-E`` flag (don't confuse this with +the ``-e`` flag for environment variables), and run repo2docker on a +local repository:: + + repo2docker -E my-repository/. + +This builds a Docker container from the files in that repository +(using, for example, a ``requirements.txt`` or ``install.R`` file), +then runs that container, while connecting the working directory +inside the container to the local repository outside the +container. For example, in case there is a notebook file (``.ipynb``), +this will open in a local webbrowser, and one can edit it and save +it. The resulting notebook is updated in both the Docker container and +the local repository. Once the container is exited, the changed file +will still be in the local repository. + +This allows for easy testing of the container while debugging some +items, as well as using a fully customizable container to edit +notebooks (among others). + +.. note:: + + Editable mode is a convenience option that will bind the + repository to the container working directory (usually + ``$HOME``). If you need to mount to a different location in + the container, use the ``--volumes`` option instead. Similarly, + for a fully customized user Dockerfile, this option is not + guaranteed to work.