Expanded documentation for command line arguments

[jhamman]

This week, I built a repo for CI/CD for building a stack of Docker images using repo2docker (see pangeo-stacks). Along the way, I encountered a few areas in the documentation that could use some tuning. I'm happy to help contribute some additional docs, but first thought it would be good to first enumerate the spots that I found lacking detail.

1. config file

--config <config>
Path to config file for repo2docker

Questions: What is the repo2docker config file? How should this be formatted? When would I use it?

https://github.com/jupyter/repo2docker/blob/18e9d2f8178fc72a69f1acb54a2be783d71355fb/repo2docker/__main__.py#L223

2. appendix and subdir

--appendix <appendix>
--subdir <subdir>

These two options lack doc strings in the command line app. The appendix in particular must be a string (not a path to a file as I first assumed). I still don't know what the subdir is.

3. push

--push
Push docker image to repository

This would benefit from a more complete description. Specifically, an example using --push and --image-name would be super useful when sorting out where to put the Dockerhub ID, image name, and tag.

4. cache

--cache-from <cache_from>

No description here. How would I use this?

---

Proposal

• Each command line option should have an example value demonstrating its use. For the --image-name option, you may have something like Name of image to be built. If unspecified will be autogenerate. (form: TARGET_IMAGE[:TAG], e.g. jupyter/myimage:latest).
• Add a section to the docs with a bunch of usage examples. Currently there are three or four examples in https://repo2docker.readthedocs.io/en/latest/usage.html but they don't cover many of the tougher to understand options.

[betatim]

--cache-from is like the argument to docker build https://docs.docker.com/engine/reference/commandline/build/ I think.

--subdir is useful if you have one repository and want to build multiple images out of them, each from a different sub directory in that repo. It was added by someone from Pangeo to help build the image for your JupyterHub from the repo that also contains the helm chart, etc.

[choldgraf]

another friendly ping on this @jhamman - it would be great to see some docs improvements! Happy to review a PR!

[deeplook]

I’m running into the same thing. Running repo2docker will produce a long build trace and tell me a URL at the end to copy/paste into a browser. If I do that it ends up showing something like http://127.0.0.1:54018/tree. But I want to have a standard browser open that for me automatically after the build. And I want to indicate I want Jupyter Lab and even with some specific notebook to be opened at the start. I know how to do this on binder, but can't do it with repo2docker, yet. I see there is a promissing `--appendix' flag mentioned above, but the docs is not enough to tell me how to do it.