Repo2docker: Document new content provider infra

[choldgraf]

In https://github.com/jupyter/repo2docker/pull/242 @betatim added some new infrastructure for defining new content providers. However, I don't believe that any documentation was added as a part of this. We should:

• Document how to add a new content provider
• Document what content providers are currently supported
• Make it clear that people can use different content providers in their repos

[betatim]

Make it clear that people can use different content providers in their repos

We can't mix content providers together at the moment .Each "repo" has to be provided by one content provider. I hadn't thought about the possibility of composing/mixing them. Do you think that would be useful? At first glance it makes my head hurt to think about it :)

👍 on the other points. So far for the users nothing has changed, but we should figure out where in the docs to talk about content providers in anticipation of Zenodo/OSF/X providers.

[choldgraf]

I agree - I just meant "people can use different providers for different repos" not "use multiple providers for the same repo"

I mostly want a clear path forward for contributions from potential contributor X who wants provider Y supported 😊

[betatim]

How about splitting "Advanced and developer information" into two sections? Or maybe even removing the resulting new "Advanced" section by moving FAQ to "getting started" (it feels weird having frequently asked questions in the advanced instead of beginner section) and moving "r2d in your CI" to the Howto section.

Then the developer part could be about all the things it is right now, CONTRIBUTING.md (see #439) and content providers?

[choldgraf]

+1 to that!

[pdurbin]

I just referenced the new content provider infrastructure at https://github.com/IQSS/dataverse/issues/4714#issuecomment-479869004 and I would have loved to have linked to docs so +1 for docs, please. :smile:

[pdurbin]

For now people should look at https://github.com/jupyter/repo2docker/blob/80b979f8580ddef184d2ba7d354e7a833cfa38a4/repo2docker/contentproviders/base.py#L16-L60

[choldgraf]

I'm gonna add this one to the next milestone because I think it's pretty important for others to build off of repo2docker

[betatim]

To me it is unclear what the next step is. Should we improve the docstrings? Should we copy the docstrings to the actual docs? As someone who wants to extend/write a new content provider I'd expect you to go and look at the existing code. Which is where you'd find these docs and the existing content providers as an example to build off.

One thing that isn't explained here is how different content providers are tried or when it stops. The answer is: each content provider is tried in turn until one of them matches (dectec() returns not None) at which point that provider is used.