adding instructions for contentprovider extension

docs/source/architecture.md

@@ -1,8 +1,12 @@
-# Architecture of repo2docker
+# Architecture
 
 This is a living document talking about the architecture of repo2docker
 from various perspectives.
 
+```eval_rst
+.. _buildpacks:
+```
+
 ## Buildpacks
 
 The **buildpack** concept comes from [Heroku](https://devcenter.heroku.com/articles/buildpacks)
@@ -39,9 +43,9 @@ It takes the following steps to determine this:
    libraries can check for presence of an `environment.yml` file and say 'yes, I can handle this
    repository' by returning `True`. Usually buildpacks look for presence of specific files
    (`requirements.txt`, `environment.yml`, `install.R`, `manifest.xml` etc) to determine if they can handle a
-   repository or not. Buildpacks may also look into specific files to determine specifics of the 
+   repository or not. Buildpacks may also look into specific files to determine specifics of the
    required environment, such as the Stencila integration which extracts the required language-specific
-   executions contexts from an XML file (see base `BuildPack`). More than one buildpack may use such 
+   executions contexts from an XML file (see base `BuildPack`). More than one buildpack may use such
    information, as properties can be inherited (e.g. the R buildpack uses the list of required Stencila
    contexts to see if R must be installed).
 3. If no `BuildPack` returns true, then repo2docker will use the default `BuildPack` (defined in

docs/source/contributing/buildpack.md

@@ -1,8 +1,10 @@
-# Adding a new buildpack to repo2docker
+# Add a new buildpack
 
 A new buildpack is needed when a new language or a new package manager should be
-supported. Existing buildpacks are a good model for how new buildpacks
+supported. [Existing buildpacks](https://github.com/jupyter/repo2docker/tree/master/repo2docker/buildpacks)
-should be structured.
+are a good model for how new buildpacks should be structured.
+See [the Buildpacks page](buildpacks) for more information about the
+structure of a buildpack.
 
 ## Criteria to balance and consider
 
@@ -17,7 +19,7 @@ Criteria to balance are:
    this using one of the escape hatches in (2), so let us make it easy and add
    native support".
 
-## Adding libraries or UI to existing buildpacks
+### Adding libraries or UI to existing buildpacks
 
 Note that this doesn't apply to adding additional libraries / UI to existing
 buildpacks. For example, if we had an R buildpack and it supported IRKernel,

docs/source/contributing/contentprovider.rst

@@ -0,0 +1,18 @@
+==========================
+Add a new content provider
+==========================
+
+Adding a new content provider allows repo2docker to grab repositories from new
+locations on the internet. To do so, you should take the following steps:
+
+#. Sub-class the `ContentProvider class <https://github.com/jupyter/repo2docker/blob/master/repo2docker/contentproviders/base.py#L17>`_.
+   This will give you a skeleton class you can modify to support your new
+   content provider.
+#. Implement a **detect()** method for the class. This takes an input
+   string (e.g., a URL or path) and determines if it points to this particular
+   content provider. It should return a dictionary (called
+   ``spec`` that will be passed to the ``fetch()`` method. `For example, see the ZenodoProvider detect method <https://github.com/jupyter/repo2docker/pull/693/files#diff-a96fcf624176b06e21c3ef7f6f6a425bR31>`_.
+#. Implement a **fetch()** method for the class. This takes the dictionary ``spec`` as input, and
+   ensures the repository exists on disk (e.g., by downloading it) and
+   returns a path to it.
+   `For example, see the ZenodoProvider fetch method <https://github.com/jupyter/repo2docker/pull/693/files#diff-a96fcf624176b06e21c3ef7f6f6a425bR57>`_.

docs/source/contributing/contributing.md

@@ -1,4 +1,4 @@
-# Contributing to repo2docker development
+# Contributing to repo2docker
 
 Thank you for thinking about contributing to repo2docker!
 This is an open source project that is developed and maintained entirely by volunteers.

docs/source/contributing/index.rst

@@ -14,4 +14,5 @@ repo2docker package.
    ../architecture
    ../design
    tasks
-   buildpack
+   buildpack
+   contentprovider

docs/source/contributing/roadmap.md

@@ -1,4 +1,4 @@
-# The repo2docker roadmap
+# Roadmap
 
 This roadmap collects "next steps" for repo2docker. It is about creating a
 shared understanding of the project's vision and direction amongst