Merge pull request #53 from choldgraf/auto_doc

updating autogen examples

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)

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

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

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.

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.

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.

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.

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.

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``.

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.

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.