Outline, include some info from READMEs

Makefile

 # Copyright (c) Jupyter Development Team.
 # Distributed under the terms of the Modified BSD License.
-.PHONY: help test
+.PHONY: docs help test
 
-# Use bash for inline if-statements in test target
+# Use bash for inline if-statements in arch_patch target
 SHELL:=bash
 OWNER:=jupyter
 ARCH:=$(shell uname -m)
@@ -54,9 +54,12 @@ dev/%: PORT?=8888
 dev/%: ## run a foreground container for a stack
 	docker run -it --rm -p $(PORT):8888 $(DARGS) $(OWNER)/$(notdir $@) $(ARGS)
 
-dev-env: # install libraries required to build docs and run tests
+dev-env: ## install libraries required to build docs and run tests
 	conda env create -f environment.yml
 
+docs: ## build HTML documentation
+	make -C docs html
+
 test/%: ## run tests against a stack
 	@TEST_IMAGE="$(OWNER)/$(notdir $@)" pytest test
 

docs/conf.py

@@ -21,17 +21,23 @@
 # import sys
 # sys.path.insert(0, os.path.abspath('.'))
 
+# For conversion from markdown to html
+import recommonmark.parser
+from recommonmark.transform import AutoStructify
+
 
 # -- General configuration ------------------------------------------------
 
 # If your documentation needs a minimal Sphinx version, state it here.
 #
-# needs_sphinx = '1.0'
+needs_sphinx = '1.4'
 
 # Add any Sphinx extension module names here, as strings. They can be
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
-extensions = []
+extensions = [
+    'jupyter_alabaster_theme'
+]
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']
@@ -78,12 +84,20 @@ pygments_style = 'sphinx'
 todo_include_todos = False
 
 
+# -- Source -------------------------------------------------------------
+
+source_parsers = {
+    '.md': 'recommonmark.parser.CommonMarkParser',
+}
+
+source_suffix = ['.rst', '.md']
+
 # -- Options for HTML output ----------------------------------------------
 
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
 #
-html_theme = 'alabaster'
+html_theme = 'jupyter_alabaster_theme'
 
 # Theme options are theme-specific and customize the look and feel of a theme
 # further.  For a list of options available for each theme, see the
@@ -96,18 +110,6 @@ html_theme = 'alabaster'
 # so a file named "default.css" will overwrite the builtin "default.css".
 html_static_path = ['_static']
 
-# Custom sidebar templates, must be a dictionary that maps document names
-# to template names.
-#
-# This is required for the alabaster theme
-# refs: http://alabaster.readthedocs.io/en/latest/installation.html#sidebars
-html_sidebars = {
-    '**': [
-        'relations.html',  # needs 'show_related': True theme option to display
-        'searchbox.html',
-    ]
-}
-
 
 # -- Options for HTMLHelp output ------------------------------------------
 

docs/contributing.md

+# Contributing
+
+## Package Updates
+
+## New Packages
+
+## Tests
+
+## Community Stacks
\ No newline at end of file

docs/index.rst

-.. docker-stacks documentation master file, created by
-   sphinx-quickstart on Fri Dec 29 20:32:10 2017.
-   You can adapt this file completely to your liking, but it should at least
-   contain the root `toctree` directive.
+Jupyter Docker Stacks
+=====================
 
-Welcome to docker-stacks's documentation!
-=========================================
+Jupyter Docker Stacks are a set of ready-to-run Docker images containing Jupyter applications and interactive computing tools. You can use a stack image to start a personal Jupyter Notebook server in a local Docker container, to run JupyterLab servers for a team using JupyterHub, to write your own project Dockerfile, and so on.
+
+**Table of Contents**
 
 .. toctree::
-   :maxdepth: 2
-   :caption: Contents:
+   :maxdepth: 1
+
+   using
+   features
+   contributing
+
+Quick Start
+-----------
 
+The examples below may help you get started if you have Docker installed, know which Docker image you want to use, and want to launch a single Jupyter Notebook server in a container. The other pages in this documentation describe additional uses and features in detail.::
 
+    # Run a Jupyter Notebook server in a Docker container started
+    # from the jupyter/scipy-notebook image built from Git commit 27ba573.
+    # All files saved in the container are lost when the notebook server exits.
+    # -ti: pseudo-TTY+STDIN open, so the logs appear in the terminal
+    # -rm: remove the container on exit
+    # -p: publish the notebook port 8888 as port 8888 on the host
+    docker run -ti --rm -p 8888:8888 jupyter/scipy-notebook:27ba573
 
-Indices and tables
-==================
+    # Run a Jupyter Notebook server in a Docker container started from the
+    # jupyter/r-notebook image built from Git commit cf1a3aa.
+    # All files written to ~/work in the container are saved to the
+    # current working on the host and persist even when the notebook server
+    # exits.
+    docker run -ti --rm -p 8888:8888 -v "$PWD":/home/jovyan/work jupyter/r-notebook:cf1a3aa
 
-* :ref:`genindex`
-* :ref:`modindex`
-* :ref:`search`
+    # Run a Jupyter Notebook server in a background Docker container started
+    # from the latest jupyter/all-spark-notebook image available on the local
+    # machine or Docker Cloud. All files saved in the container are lost
+    # when the container is destroyed.
+    # -d: detach, run container in background.
+    # -P: Publish all exposed ports to random ports
+    docker run -d -P jupyter/all-spark-notebook:latest

docs/using.md

+# Users Guide
+
+Using one of the Jupyter Docker Stacks requires two choices:
+
+1. Which Docker image you wish to use
+2. How you wish to start Docker containers from that image
+
+This section provides details about the available images and runtimes to inform your choices.
+
+## Selecting an Image
+
+### Core Stacks
+
+The Jupyter team maintains a set of Docker image definitions in the https://github.com/jupyter/docker-stacks GitHub repository. The following table describes these images, and links to their source on GitHub and their builds on Docker Cloud.
+
+|Name                        |Description|GitHub |Image Tags|
+|----------------------------|-----------|-----------|----------|
+|jupyter/base-notebook       ||||
+|jupyter/minimal-notebook    ||||
+|jupyter/r-notebook          ||||
+|jupyter/scipy-notebook      ||||
+|jupyter/datascience-notebook||||
+|jupyter/tensorflow-notebook ||||
+|jupyter/pyspark-notebook    ||||
+|jupyter/all-spark-notebook  ||||
+|----------------------------|-|-|-|
+
+#### Image Relationships
+
+The following diagram depicts the build dependencies between the core images (aka the `FROM` statement in their Dockerfiles). Any image lower in the tree inherits
+
+[![Image inheritance diagram](internal/inherit-diagram.svg)](http://interactive.blockdiag.com/?compression=deflate&src=eJyFzTEPgjAQhuHdX9Gws5sQjGzujsaYKxzmQrlr2msMGv-71K0srO_3XGud9NNA8DSfgzESCFlBSdi0xkvQAKTNugw4QnL6GIU10hvX-Zh7Z24OLLq2SjaxpvP10lX35vCf6pOxELFmUbQiUz4oQhYzMc3gCrRt2cWe_FKosmSjyFHC6OS1AwdQWCtyj7sfh523_BI9hKlQ25YdOFdv5fcH0kiEMA)
+
+#### Versioning
+
+[Click here for a commented build history of each image, with references to tag/SHA values.](https://github.com/jupyter/docker-stacks/wiki/Docker-build-history)
+
+The following are quick-links to READMEs about each image and their Docker image tags on Docker Cloud:
+
+* base-notebook: [README](https://github.com/jupyter/docker-stacks/tree/master/base-notebook), [SHA list](https://hub.docker.com/r/jupyter/base-notebook/tags/)
+* minimal-notebook: [README](https://github.com/jupyter/docker-stacks/tree/master/minimal-notebook), [SHA list](https://hub.docker.com/r/jupyter/minimal-notebook/tags/)
+* scipy-notebook: [README](https://github.com/jupyter/docker-stacks/tree/master/scipy-notebook), [SHA list](https://hub.docker.com/r/jupyter/scipy-notebook/tags/)
+* r-notebook: [README](https://github.com/jupyter/docker-stacks/tree/master/r-notebook), [SHA list](https://hub.docker.com/r/jupyter/r-notebook/tags/)
+* tensorflow-notebook: [README](https://github.com/jupyter/docker-stacks/tree/master/tensorflow-notebook), [SHA list](https://hub.docker.com/r/jupyter/tensorflow-notebook/tags/)
+* datascience-notebook: [README](https://github.com/jupyter/docker-stacks/tree/master/datascience-notebook), [SHA list](https://hub.docker.com/r/jupyter/datascience-notebook/tags/)
+* pyspark-notebook: [README](https://github.com/jupyter/docker-stacks/tree/master/pyspark-notebook), [SHA list](https://hub.docker.com/r/jupyter/pyspark-notebook/tags/)
+* all-spark-notebook: [README](https://github.com/jupyter/docker-stacks/tree/master/all-spark-notebook), [SHA list](https://hub.docker.com/r/jupyter/all-spark-notebook/tags/)
+
+
+The latest tag in each Docker Hub repository tracks the master branch HEAD reference on GitHub. This is a moving target and will make backward-incompatible changes regularly.
+Any 12-character image tag on Docker Hub refers to a git commit SHA here on GitHub. See the Docker build history wiki page for a table of build details.
+Stack contents (e.g., new library versions) will be updated upon request via PRs against this project.
+Users looking for reproducibility or stability should always refer to specific git SHA tagged images in their work, not latest.
+For legacy reasons, there are two additional tags named 3.2 and 4.0 on Docker Hub which point to images prior to our versioning scheme switch.
+If you haven't already, pin your image to a tag, e.g. FROM jupyter/scipy-notebook:7c45ec67c8e7. latest is a moving target which can change in backward-incompatible ways as packages and operating systems are updated.
+
+## Community Stacks
+
+The Jupyter community maintains additional
+
+## Running a Container
+
+### Using the Docker Command Line
+
+### Using JupyterHub
+
+Every notebook stack is compatible with JupyterHub 0.5 or higher. When running with JupyterHub, you must override the Docker run command to point to the `start-singleuser.sh script, which starts a single-user instance of the Notebook server. See each stack's README for instructions on running with JupyterHub.
+
+### Using Binder
\ No newline at end of file