updating autogen examples
MODIFY
docs/source/conf.py
docs/source/conf.py
@@ -186,14 +186,18 @@ epub_exclude_files = ['search.html']
# Build the repo2docker test syntax
from glob import glob
+import numpy as np
import os
s = ''
+FILE_ORDER_PREFERENCE = ['System', 'Python', 'Julia', 'Docker', 'Misc']
+FILES_DICT = {ii: [] for ii in FILE_ORDER_PREFERENCE}
for folder, _, files in os.walk(os.path.join('..', '..', 'tests')):
if 'README.rst' not in files:
continue
header = files.pop(files.index('README.rst'))
with open(os.path.join(folder, header), 'r') as ff:
- s += ff.read() + '\n'
+ this_s = ff.read() + '\n'
+ title = this_s.split('\n')[0]
for ifile in files:
filename = os.path.basename(ifile)
if filename == 'verify':
@@ -201,10 +205,15 @@ for folder, _, files in os.walk(os.path.join('..', '..', 'tests')):
with open(os.path.join(folder, ifile), 'r') as ff:
lines = ff.readlines()
lines = [' ' + line for line in lines]
- this_s = '``{}``\n{}\n\n**Contents**::\n\n'.format(
- filename, '~' * (len(filename) + 4))
+ this_s += 'File: ``{}``\n{}\n\n**Contents**::\n\n'.format(
+ filename, '~' * (len(filename) + 10))
this_s += '\n'.join(lines)
this_s += '\n\n'
- s += this_s
+ usename = [ii for ii in FILE_ORDER_PREFERENCE if ii in title]
+ usename = 'Misc' if len(usename) == 0 else usename[0]
+ FILES_DICT[usename].append(this_s)
+for key in FILE_ORDER_PREFERENCE:
+ for istring in FILES_DICT[key]:
+ s += istring
with open('./generated/test_file_text.txt', 'w') as ff:
ff.write(s)

MODIFY
docs/source/index.rst
docs/source/index.rst
-.. repo2docker documentation master file, created by
- sphinx-quickstart on Fri Jun 2 13:00:51 2017.
- You can adapt this file completely to your liking, but it should at least
- contain the root `toctree` directive.
+jupyter-repo2docker
+===================
-Welcome to repo2docker's documentation!
-=======================================
+**jupyter-repo2docker** is a tool to build, run, and push Docker
+images from source code repositories. See the list below for various
+ways in which you can use ``repo2docker``.
+Site Contents
+-------------
.. toctree::
:maxdepth: 2
- :caption: Contents:
- builder
-
-Indices and tables
-==================
-
-* :ref:`genindex`
-* :ref:`modindex`
-* :ref:`search`
-
-Build Syntax
-============
-
-.. include:: generated/test_file_text.txt
+ samples

ADD
docs/source/samples.rst
+Sample build files
+==================
+
+There are many options for specifying your environment with ``repo2docker``.
+The following sections describe a few samples to get you started.
+
+.. include:: generated/test_file_text.txt

ADD
tests/dockerfile/jupyter-stack/README.rst
+Docker - Specifying dependencies
+--------------------------------
+
+You can specify dependencies with Dockerfiles, which may be more flexible
+in running non-standard code. We recommend sourcing your Dockerfile from
+one of the Jupyter base images. In this case, we use a stripped-down image
+that has minimal dependencies installed.

ADD
tests/dockerfile/legacy/README.rst
+Docker - Legacy Dockerfiles
+---------------------------
+
+This demonstrates the Dockerfile syntax that was often found in the first
+version of Binder. It sources the ``andrewosh`` Docker image, which
+contained many different dependencies, then installs Julia. We encourage
+users to source one of the Jupyter base images as they are more streamlined.

ADD
tests/dockerfile/simple/README.rst
+Docker - Running scripts
+------------------------
+
+It's possible to run scripts using Docker in your build. In this case, we run
+a simple shell script after installing dependencies. However, we recommend
+that you see if it's possible to accomplish what you want using ``apt`` and
+``postInstall`` files, and use Dockerfiles only when necessary.

MODIFY
tests/julia/pyplot/README.rst
tests/julia/pyplot/README.rst
@@ -3,3 +3,5 @@ Julia - REQUIRE
The simplest way to specify dependencies in Julia, a REQUIRE file simply
lists the names of packages. Each one will be installed but not pre-compiled.
+In this case, we also specify python dependencies with an ``environment.yml``
+file.

ADD
tests/venv/apt-packages/README.rst
+System - APT Packages
+---------------------
+
+It is possible to install packages using the Shell with the ``apt.txt`` file.
+In this case we install ``gfortran`` which does not have an easy Python install.

ADD
tests/venv/numpy/README.rst
+Python - Requirements.txt
+-------------------------
+
+The simplest way to specify Python packages is with a ``requirements.txt`` file
+that is compatible with ``pip install``.

ADD
tests/venv/postBuild/README.rst
+System - Post-build scripts
+---------------------------
+
+It is possible to run scripts after you've built the environment specified in
+your other files. This could be used to, for example, download data or run
+some configuration scripts. For example, this will download and install a
+Jupyter extension.

ADD
tests/venv/py2/README.rst
+System - Specifying runtime environments
+----------------------------------------
+
+You can specify runtime environments (such as Python 2 or 3) with a
+``runtime.txt`` file.

updating autogen examples