[MRG] Add build pack documentation #36
Conversation
doc/dockerfile.rst
Outdated
| @@ -19,6 +19,12 @@ This guide will help you in preparing your Dockerfile so that it has the | |||
| components needed to run JupyterHub, allowing it to work on Binder | |||
| deployments. | |||
|
|
|||
| .. note:: | |||
There was a problem hiding this comment.
My attempt at making really sure people don't venture past this warning unless they really know what they are doing.
There was a problem hiding this comment.
Use important directive:
.. important::
| dockerfile | ||
| reproducibility | ||
| sample_repos | ||
| faq | ||
|
|
There was a problem hiding this comment.
Moved this into introdcution.rst because as a reader I rarely expect to find stuff below the TOC. I read the welcome blah above the TOC, then start scanning for what I am looking for, follow the link. Opinions?
|
What else is worth highlighting in |
doc/introduction.rst
Outdated
| @@ -0,0 +1,39 @@ | |||
| Welcome to using binder! | |||
There was a problem hiding this comment.
the Binder user documentation?
|
Once this is merged we should add a link on the mybinder.org landing page that links to the |
|
Seems like a good addition to me, only one comment. Feel free to open a binderhub PR where we can discuss where to link it. |
betatim
changed the title
|
Let's let this stew a bit to give more people a change to comment. |
|
Merge? |
doc/introduction.rst
Outdated
| @@ -0,0 +1,39 @@ | |||
| Welcome to the binder documentation | |||
doc/preparing.rst
Outdated
| users of your Binder. | ||
| * One (or many) text files that specify the requirements of your code. For | ||
| example, a ``requirements.txt`` or ``environment.yml`` file. See the | ||
| below examples for a list of all the files and environments that are |
There was a problem hiding this comment.
...a list of supported files and environments.
doc/preparing.rst
Outdated
| below examples for a list of all the files and environments that are | ||
| supported. | ||
|
|
||
| All you need to do is include the files specified above in a GitHub repository. |
There was a problem hiding this comment.
Verify, and add if needed, the files specified above to the repository.
doc/preparing.rst
Outdated
| .. note:: | ||
|
|
||
| If a previous version of the repository has already been built, Binder will | ||
| only build a new one if the git hashes don't match. If Binder *doesn't* have |
There was a problem hiding this comment.
When Binder doesn't need to build a repository, ...
doc/preparing.rst
Outdated
| computational environment is much faster. | ||
|
|
||
|
|
||
| Simple python dependencies |
doc/preparing.rst
Outdated
| Using python2 | ||
| ------------- | ||
|
|
||
| To use python 2.7 for your repository create a ``runtime.txt`` with |
| .. note:: | ||
|
|
||
| Make sure that you save your notebooks with a python2 kernel activated, | ||
| as this defines which kernel Binder will use when a notebook is opened. |
There was a problem hiding this comment.
The active kernel is displayed in the upper right corner of the notebook.
doc/preparing.rst
Outdated
| installed into the python3 environment. | ||
|
|
||
|
|
||
| Executing commands as part of the build |
There was a problem hiding this comment.
Executing post-build commands
doc/preparing.rst
Outdated
|
|
||
| You might need to run arbitrary commands at the end of the build process. Place | ||
| these in the ``postBuild`` file and make it executable. One use case is having | ||
| a repository that contains a python package and examples that use the package. |
doc/dockerfile.rst
Outdated
| @@ -19,6 +19,12 @@ This guide will help you in preparing your Dockerfile so that it has the | |||
| components needed to run JupyterHub, allowing it to work on Binder | |||
| deployments. | |||
|
|
|||
| .. note:: | |||
There was a problem hiding this comment.
Use important directive:
.. important::
|
I'm +1 on merge once @willingc 's comments are addressed |
|
All suggestions got applied. There is only one about |
|
Thank @willingc you for fixing all that shockingly bad spelling. |
|
paging Dr @choldgraf to the merge department, Dr @choldgraf ;) |
| Using conda packages | ||
| -------------------- | ||
|
|
||
| For 'complex to install' packages, like ``numpy`` or ``scikit-learn``, we |
There was a problem hiding this comment.
I think you should pick a different example now :D numpy nor scikit-learn are no longer complex to install with requirements.txt IMO :D MNE perhaps?
There was a problem hiding this comment.
MNE? If you can think of something that isn't an ipywidget we can change it. I couldn't think of anything off the top of my head. gdal? but then that isn't a python package really.
Ja, damn those wheels ...
There was a problem hiding this comment.
hands down geopandas. anything in the geospatial analytics world sucks to install with pip. Also make sure we use conda-forge.
This makes a start on jupyterhub/binderhub#300