diff --git a/docs/source/conf.py b/docs/source/conf.py index ac9ce6b5..03c79c9f 100644 --- a/docs/source/conf.py +++ b/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) diff --git a/docs/source/index.rst b/docs/source/index.rst index bafcd6a5..42f15120 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -1,25 +1,13 @@ -.. 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 diff --git a/docs/source/samples.rst b/docs/source/samples.rst new file mode 100644 index 00000000..4a1c6bfa --- /dev/null +++ b/docs/source/samples.rst @@ -0,0 +1,7 @@ +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 diff --git a/tests/dockerfile/jupyter-stack/README.rst b/tests/dockerfile/jupyter-stack/README.rst new file mode 100644 index 00000000..a42bbf09 --- /dev/null +++ b/tests/dockerfile/jupyter-stack/README.rst @@ -0,0 +1,7 @@ +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. diff --git a/tests/dockerfile/legacy/README.rst b/tests/dockerfile/legacy/README.rst new file mode 100644 index 00000000..4fbf441b --- /dev/null +++ b/tests/dockerfile/legacy/README.rst @@ -0,0 +1,7 @@ +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. diff --git a/tests/dockerfile/simple/README.rst b/tests/dockerfile/simple/README.rst new file mode 100644 index 00000000..2b11ee48 --- /dev/null +++ b/tests/dockerfile/simple/README.rst @@ -0,0 +1,7 @@ +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. diff --git a/tests/julia/pyplot/README.rst b/tests/julia/pyplot/README.rst index 197c2a4c..87568848 100644 --- a/tests/julia/pyplot/README.rst +++ b/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. diff --git a/tests/venv/apt-packages/README.rst b/tests/venv/apt-packages/README.rst new file mode 100644 index 00000000..a37d88b7 --- /dev/null +++ b/tests/venv/apt-packages/README.rst @@ -0,0 +1,5 @@ +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. diff --git a/tests/venv/numpy/README.rst b/tests/venv/numpy/README.rst new file mode 100644 index 00000000..71bae4f5 --- /dev/null +++ b/tests/venv/numpy/README.rst @@ -0,0 +1,5 @@ +Python - Requirements.txt +------------------------- + +The simplest way to specify Python packages is with a ``requirements.txt`` file +that is compatible with ``pip install``. diff --git a/tests/venv/postBuild/README.rst b/tests/venv/postBuild/README.rst new file mode 100644 index 00000000..872b2d6e --- /dev/null +++ b/tests/venv/postBuild/README.rst @@ -0,0 +1,7 @@ +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. diff --git a/tests/venv/py2/README.rst b/tests/venv/py2/README.rst new file mode 100644 index 00000000..8c125c92 --- /dev/null +++ b/tests/venv/py2/README.rst @@ -0,0 +1,5 @@ +System - Specifying runtime environments +---------------------------------------- + +You can specify runtime environments (such as Python 2 or 3) with a +``runtime.txt`` file.