From de3658442bf40e05bb0be276387ec29e4729bcb8 Mon Sep 17 00:00:00 2001 From: Min RK Date: Thu, 21 Feb 2019 10:20:56 +0100 Subject: [PATCH] update docs for pinning Python - clarify that runtime.txt is only for env files that don't support runtime specification - specify default version of Python and when it changed - more links to pinning docs --- docs/source/config_files.rst | 50 ++++++++++++++++++++++++--------- docs/source/faq.rst | 7 +++-- docs/source/howto/languages.rst | 35 +++++++++++++++-------- 3 files changed, 63 insertions(+), 29 deletions(-) diff --git a/docs/source/config_files.rst b/docs/source/config_files.rst index f1f21bc3..5295d8c0 100644 --- a/docs/source/config_files.rst +++ b/docs/source/config_files.rst @@ -23,15 +23,14 @@ Below is a list of supported configuration files (roughly in the order of build :local: :depth: 1 -.. _environment-yml: +.. _environment.yml: ``environment.yml`` - Install a Python environment ================================================== -``environment.yml`` is the standard configuration file used by Anaconda, conda, -and miniconda that lets you install packages in the data analytics stack (it -primarily installs Python packages, though can be used to install a range of -non-Python packages as well). +``environment.yml`` is the standard configuration file used by `conda `_ +that lets you install any kind of package, +including Python, R, and C/C++ packages. .. note:: @@ -41,16 +40,18 @@ non-Python packages as well). file. You can also specify which Python version to install in your built environment -with ``environment.yml``. By default, ``repo2docker`` **installs -Python 3.6** with your ``environment.yml`` unless you include the version of -Python in the file. ``conda`` supports Python versions 3.6, 3.5, 3.4, and 2.7. -``repo2docker`` support is best with Python 3.6, 3.5, and 2.7. +with ``environment.yml``. By default, ``repo2docker`` installs +|default_python| with your ``environment.yml`` unless you include the version of +Python in this file. ``conda`` supports all versions of Python, +though ``repo2docker`` support is best with Python 3.7, 3.6, 3.5 and 2.7. .. warning:: If you include a Python version in a ``runtime.txt`` file in addition to your ``environment.yml``, your ``runtime.txt`` will be ignored. +.. _requirements.txt: + ``requirements.txt`` - Install a Python environment =================================================== @@ -60,6 +61,8 @@ environment. Our on GitHub shows a typical requirements file. +.. _setup.py: + ``setup.py`` - Install Python packages ====================================== @@ -68,6 +71,8 @@ To install your repository like a Python package, you may include a ``pip install -e .``. +.. _REQUIRE: + ``REQUIRE`` - Install a Julia environment ========================================= @@ -76,6 +81,8 @@ Julia repository with ``REQUIRE`` and ``environment.yml``, visit `binder-examples/julia-python `_. +.. _install.R: + ``install.R`` - Install an R/RStudio environment ================================================ @@ -85,6 +92,8 @@ To set the date of the snapshot add a runtime.txt_. For an example ``install.R`` file, visit our `example install.R file `_. +.. _apt.txt: + ``apt.txt`` - Install packages with apt-get =========================================== @@ -95,6 +104,8 @@ We use ``apt.txt``, for example, to install LaTeX in our `example apt.txt for LaTeX `_. +.. _DESCRIPTION: + ``DESCRIPTION`` - Install an R package ====================================== @@ -106,6 +117,9 @@ You also need to have a ``runtime.txt`` file that is formatted as ``r---
``, where YYYY-MM-DD is a snapshot of MRAN that will be used for your R installation. + +.. _manifest.xml: + ``manifest.xml`` - Install Stencila =================================== @@ -154,21 +168,29 @@ If you only need to run things once during the build phase use :ref:`postBuild`. .. TODO: Discuss runtime limits, best practices, etc. - Also, point to an example. .. _runtime.txt: ``runtime.txt`` - Specifying runtimes ===================================== -This allows you to control the runtime of Python or R. +Sometimes you want to specify the version of the runtime +(e.g. the version of Python or R), +but the environment specification format don't let you specify this information +(e.g. requirements.txt or install.R). +For these cases, we have a special file, ``runtime.txt``. + +.. note:: + + ``runtime.txt`` is only supported when used with environment specifications + that do not already support specifying the runtime + (e.g. when using ``environment.yml`` for conda or ``REQUIRE`` for Julia, + ``runtime.txt`` will be ignored). To use python-2.7: add ``python-2.7`` in runtime.txt file. -The repository will run in a virtualenv with +The repository will run in an env with Python 2 installed. To see a full example repository, visit our `Python2 example `_. -**Python versions in** ``runtime.txt`` **are ignored when** ``environment.yml`` **is -present in the same folder**. repo2docker uses R libraries pinned to a specific snapshot on `MRAN `_. diff --git a/docs/source/faq.rst b/docs/source/faq.rst index 48c55739..c16869c8 100644 --- a/docs/source/faq.rst +++ b/docs/source/faq.rst @@ -9,7 +9,8 @@ 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. +One can specify a Python version in the ``environment.yml`` file of a repository +or ``runtime.txt`` file if using ``requirements.txt`` instead of ``environment.yml``. What versions of Python (or R or Julia...) are supported? --------------------------------------------------------- @@ -19,8 +20,8 @@ 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.7 (added in 0.7, default in 0.8) +- 3.6 (default in 0.7 and earlier) - 3.5 Additional versions may work, as long as the diff --git a/docs/source/howto/languages.rst b/docs/source/howto/languages.rst index a71ec96f..7fa3bafb 100644 --- a/docs/source/howto/languages.rst +++ b/docs/source/howto/languages.rst @@ -16,30 +16,41 @@ you use one of the following configuration files: * ``requirements.txt`` * ``environment.yml`` -Note that by default, the environment will have **Python 3** installed. +.. note:: + + By default, the environment will have |default_python|. + +.. versionchanged:: 0.8 + + Upgraded default Python from 3.6 to 3.7. + Specifying a version of Python ------------------------------ To specify a specific version of Python, you have two options: -* Use ``runtime.txt``. Include a line that specifies the Python version in - this file. This line takes the following form:: - - python=X.X - - For example,:: - - python=2.7 -* Use ``environment.yml``. The Anaconda distribution also lets you define - the Python environment within ``environment.yml``. To do so, add ``python=X.X`` - to your dependencies section, like so:: +* Use :ref:`environment.yml `. Conda environments let you define + the Python version in ``environment.yml``. + To do so, add ``python=X.X`` to your dependencies section, like so:: name: python 2.7 dependencies: - python=2.7 - numpy +* Use :ref:`runtime.txt ` with :ref:`requirements.txt `. + If you are using ``requirements.txt`` instead of ``environment.yml``, + you can specify the Python runtime version in a separate file called ``runtime.txt``. + This file contains a single line of the following form:: + + python-X.X + + For example:: + + python-3.6 + + The R Language ==============