adding repoproviders documentation (#1017)

adding repoproviders documentation
jupyterhub · Dec 5, 2019 · c81a986 · c81a986
2 parents bcadc59 + 0316406
commit c81a986
Show file tree

Hide file tree

Showing 5 changed files with 122 additions and 30 deletions.
diff --git a/binderhub/repoproviders.py b/binderhub/repoproviders.py
@@ -1,11 +1,11 @@
 """
-Classes for Repo providers
+Classes for Repo providers.
 
 Subclass the base class, ``RepoProvider``, to support different version
 control services and providers.
 
-Note: When adding a new repo provider, add it to the allowed values for
-      repo providers in event-schemas/launch.json.
+.. note:: When adding a new repo provider, add it to the allowed values for
+          repo providers in event-schemas/launch.json.
 """
 from datetime import timedelta
 import json
@@ -339,7 +339,7 @@ def get_resolved_ref(self):
                                 .format(self.unresolved_ref))
             resolved_ref = result.stdout.split(None, 1)[0]
             self.sha1_validate(resolved_ref)
-            self.resolved_ref = resolved_ref 
+            self.resolved_ref = resolved_ref
         else:
             # The ref already was a valid SHA hash
             self.resolved_ref = self.unresolved_ref
@@ -499,7 +499,7 @@ class GitHubRepoProvider(RepoProvider):
     api_base_path = Unicode('https://api.{hostname}',
         config=True,
         help="""The base path of the GitHub API
-        
+
         Only necessary if not github.com,
         e.g. GitHub Enterprise.
 
@@ -652,7 +652,7 @@ def github_api_request(self, api_url, etag=None):
             log("GitHub rate limit remaining {remaining}/{limit}. Reset in {delta}.".format(
                 remaining=remaining, limit=rate_limit, delta=delta,
             ))
-        
+
         return resp
 
     @gen.coroutine
@@ -661,7 +661,7 @@ def get_resolved_ref(self):
             return self.resolved_ref
 
         api_url = "{api_base_path}/repos/{user}/{repo}/commits/{ref}".format(
-            api_base_path=self.api_base_path.format(hostname=self.hostname), 
+            api_base_path=self.api_base_path.format(hostname=self.hostname),
             user=self.user, repo=self.repo, ref=self.unresolved_ref
         )
         self.log.debug("Fetching %s", api_url)
@@ -720,6 +720,7 @@ class GistRepoProvider(GitHubRepoProvider):
     The ref is optional, valid values are
         - a full sha1 of a ref in the history
         - master
+
     If master or no ref is specified the latest revision will be used.
     """
 

diff --git a/doc/api.rst b/doc/api.rst
@@ -12,31 +12,15 @@ There's one API endpoint, which is:
 
 Even though it says **build** it actually performs **launch**.
 
-**provider_prefix** identifies the provider.
-**spec** defines the source of the computing environment to be built and 
-served using the given provider.
-See :ref:`providers-section` for supported inputs.
+* **provider_prefix** identifies the provider.
+* **spec** defines the source of the computing environment to be built and
+  served using the given provider.
 
-.. _providers-section:
+.. note:: The **provider_prefix** can be any of the supported
+          repository providers in BinderHub, see the
+          :ref:`providers-section` section for supported inputs.
 
-Providers
----------
-
-Currently supported providers, their prefixes and specs are:
-
-+------------+--------------------+-------------------------------------------------------------+----------------------------+
-| Provider   | provider_prefix    | spec                                                        | notes                      |
-+============+====================+=============================================================+============================+
-| GitHub     | ``gh``             | ``<user>/<repo>/<commit-sha-or-tag-or-branch>``             |                            |
-+------------+--------------------+-------------------------------------------------------------+----------------------------+
-| Git        | ``git``            | ``<url-escaped-url>/<commit-sha>``                          | arbitrary HTTP git repos   |
-+------------+--------------------+-------------------------------------------------------------+----------------------------+
-| GitLab     | ``gl``             | ``<url-escaped-namespace>/<commit-sha-or-tag-or-branch>``   |                            |
-+------------+--------------------+-------------------------------------------------------------+----------------------------+ 
-| Gist       | ``gist``           | ``<github-username>/<gist-id><commit-sha-or-tag>``          |                            |
-+------------+--------------------+-------------------------------------------------------------+----------------------------+
-
-Next, construct an appropriate URL and send a request.
+To use this endpoint, construct an appropriate URL and send a request.
 
 You'll get back an `Event
 Stream <https://developer.mozilla.org/en-US/docs/Web/API/Server-sent_events/Using_server-sent_events>`__.
@@ -56,6 +40,7 @@ When the request is received, the following happens:
 4. If the build succeeds, we contact the JupyterHub API and start
    launching the server.
 
+
 Events
 ------
 

diff --git a/doc/developer/index.rst b/doc/developer/index.rst
@@ -10,4 +10,5 @@ A more detailed overview of the BinderHub design, architecture, and functionalit
    ../overview
    ../eventlogging
    ../api
+   repoproviders
    ../reference/ref-index.rst
diff --git a/doc/developer/repoproviders.rst b/doc/developer/repoproviders.rst
@@ -0,0 +1,67 @@
+.. _providers-section:
+
+====================
+Repository Providers
+====================
+
+Repository Providers (or RepoProviders) are
+locations where repositories are stored (e.g.,
+GitHub). BinderHub supports a number of providers out of the
+box, and can be extended to support new providers. For a complete
+listing of the provider classes, see :ref:`api-repoproviders`.
+
+Supported repoproviders
+=======================
+
+Currently supported providers, their prefixes and specs are:
+
+.. table::
+    :widths: 5 5 55 35
+
+    +------------+--------------------+-------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------+
+    | Provider   | provider_prefix    | spec                                                        | notes                                                                                                                                     |
+    +============+====================+=============================================================+===========================================================================================================================================+
+    | GitHub     | ``gh``             | ``<user>/<repo>/<commit-sha-or-tag-or-branch>``             | `GitHub <https://github.com/>`_ is a website for hosting and sharing git repositories.                                                    |
+    +------------+--------------------+-------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------+
+    | GitLab     | ``gl``             | ``<user>/<repo>/<commit-sha-or-tag-or-branch>``             | `GitLab <https://https://about.gitlab.com/>`_ offers hosted as well as self-hosted git repositories.                                      |
+    +------------+--------------------+-------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------+
+    | Gist       | ``gist``           | ``<github-username>/<gist-id><commit-sha-or-tag>``          | `Gists <https://gist.github.com/>`_ are small collections of files stored on GitHub. They behave like lightweight repositories.           |
+    +------------+--------------------+-------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------+
+    | Zenodo     | ``zenodo``         | ``<zenodo-DOI>``                                            | `Zenodo <https://zenodo.org/>`_ is a non-profit provider of scholarly artifacts (such as code repositories) run in partnership with CERN. |
+    +------------+--------------------+-------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------+
+    | Figshare   | ``figshare``       | ``<figshare-DOI>``                                          | `FigShare <https://figshare.com/>`_ is company that offers hosting for scholarly artifacts (such as code repositories).                   |
+    +------------+--------------------+-------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------+
+    | Git        | ``git``            | ``<url-escaped-url>/<commit-sha>``                          | A generic repository provider for URLs that point directly to a git repository.                                                           |
+    +------------+--------------------+-------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------+
+
+Adding a new repository provider
+================================
+
+It is possible to add new repository providers to BinderHub, allowing
+a BinderHub deployment to fetch repositories from new locations
+on the web. Doing so involves defining your own RepoProvider sub-class
+and modifying a set of methods/attributes to interface with the online
+provider to which you are providing access. It also often involves
+`building a new repo2docker content provider <https://github.com/jupyter/repo2docker/tree/master/repo2docker/contentproviders>`_.
+
+In order to extend the supported repository providers,
+follow these instructions. We'll provide example links for each step to a
+recent `BinderHub pull-request <https://github.com/jupyterhub/binderhub/pull/969>`_
+that implements the ``DataverseProvider`` class.
+
+#. Review the `repoprovider module <https://github.com/jupyterhub/binderhub/blob/master/binderhub/repoproviders.py>`_.
+   This shows a number of example repository providers.
+#. Check whether repo2docker has a `ContentProvider class <https://github.com/jupyter/repo2docker/tree/master/repo2docker/contentproviders>`_
+   that will work with your repository provider. If not, then you'll need to create one first.
+#. Create a new class that sub-classes the ``RepoProvider`` class.
+   Define your own methods for actions that are repository provider-specific.
+   For example, `here is the DataverseProvider class <https://github.com/jupyterhub/binderhub/pull/969/files#diff-c5688934f1e6dc3e932b6c84c1bbbd5dR298>`_.
+#. Add this class to the `list of default RepoProviders in BinderHub <https://github.com/jupyterhub/binderhub/pull/969/files#diff-a15f2374919ff29de22fa29a192b1fd1R397>`_.
+#. Add the new provider prefix `to the BinderHub UI <https://github.com/jupyterhub/binderhub/pull/969/files#diff-29b962b0b049b65a0fed0d8b5dc838b9R58>`_
+   and `the index javascript <https://github.com/jupyterhub/binderhub/pull/969/files#diff-d46aa1f6b1ea4f726708fcc1cd34e994R92>`_
+   and make the appropriate changes to the index page based on the URL
+   specification for this repository provider.
+#. Add `a test for your repoprovider <https://github.com/jupyterhub/binderhub/pull/969/files#diff-360740f27b99f96e330327e34440a0e8R102>`_
+   to ensure that it properly resolves and fetches a repository URL.
+#. Document your new repository provider on the :ref:`providers-section` page as well
+   as the :ref:`api-repoproviders` page.
diff --git a/doc/reference/repoproviders.rst b/doc/reference/repoproviders.rst
@@ -1,3 +1,5 @@
+.. _api-repoproviders:
+
 repoproviders
 =============
 
@@ -14,8 +16,44 @@ Module: :mod:`binderhub.repoproviders`
 .. autoconfigurable:: RepoProvider
     :members:
 
+
 :class:`GitHubRepoProvider`
 ---------------------------
 
 .. autoconfigurable:: GitHubRepoProvider
     :members:
+
+
+:class:`GitLabRepoProvider`
+---------------------------
+
+.. autoconfigurable:: GitLabRepoProvider
+    :members:
+
+
+:class:`GistRepoProvider`
+---------------------------
+
+.. autoconfigurable:: GistRepoProvider
+    :members:
+
+
+:class:`ZenodoProvider`
+---------------------------
+
+.. autoconfigurable:: ZenodoProvider
+    :members:
+
+
+:class:`FigshareProvider`
+---------------------------
+
+.. autoconfigurable:: FigshareProvider
+    :members:
+
+
+:class:`GitRepoProvider`
+---------------------------
+
+.. autoconfigurable:: GitRepoProvider
+    :members: