diff --git a/docs/source/architecture.md b/docs/source/architecture.md index 138e69b5..a98a2fe9 100644 --- a/docs/source/architecture.md +++ b/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 diff --git a/docs/source/contributing/buildpack.md b/docs/source/contributing/buildpack.md index 1de331a7..cd74e91e 100644 --- a/docs/source/contributing/buildpack.md +++ b/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 -should be structured. +supported. [Existing buildpacks](https://github.com/jupyter/repo2docker/tree/master/repo2docker/buildpacks) +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, diff --git a/docs/source/contributing/contentprovider.rst b/docs/source/contributing/contentprovider.rst new file mode 100644 index 00000000..6f1c806c --- /dev/null +++ b/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 `_. + 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 `_. +#. 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 `_. diff --git a/docs/source/contributing/contributing.md b/docs/source/contributing/contributing.md index 2f61d13c..346c9f1d 100644 --- a/docs/source/contributing/contributing.md +++ b/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. diff --git a/docs/source/contributing/index.rst b/docs/source/contributing/index.rst index 2973791b..09939de5 100644 --- a/docs/source/contributing/index.rst +++ b/docs/source/contributing/index.rst @@ -14,4 +14,5 @@ repo2docker package. ../architecture ../design tasks - buildpack \ No newline at end of file + buildpack + contentprovider diff --git a/docs/source/contributing/roadmap.md b/docs/source/contributing/roadmap.md index 88c6ccdd..cfaf7336 100644 --- a/docs/source/contributing/roadmap.md +++ b/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