Template for publishing reproducible experiments in Python Jupyter notebooks runnable on Binder and Azure Notebooks
- Create a new repository for your project, navigate to the directory with a clone of your repository, and start to add new content to your repository, copying it from the template and modifying as appropriate.
Alternatively, you can first import this template into your GitHub account using GitHub importer as explained at https://help.github.com/en/github/importing-your-projects-to-github/importing-a-repository-with-github-importer) and then start to modify it as appropriate.
In addition to working with a local clone of your repository, you can also use GitHub web interface.
- You may follow the structure of this template:
datadirectory for data files
codedirectory for code
notebooksdirectory for Jupyter notebooks
README.mdfile for a brief description of your project, documented dependencies, installation and usage instructions, etc.
LICENSEfile with copyright information and license details
.gitignorefile which specifies which files and directories Git should ignore
requirements.txtwith specified dependencies of your project
postBuildwith additional steps needed after installation
- Update URL for the Binder badge in the README file above.
After you commit and push these changes, go to GitHub and click on the
Binder badge. A message
Loading repository: ...will be displayed, followed by a non-interactive preview. Please be patient, since it may take a while, depending on the current load on Binder. You can click on "Show" to monitor the progress of the build in the build logs. When the server will be ready, you will see the main Jupyter screen with a file browser. Navigate to the
notebooksdirectory and open a Jupyter notebook (or create a new one).
In the Jupyter notebook you can now combine code, input and output, and a text narrative to demonstrate your code and explain how it works. Please note that the notebook on Binder will not be preserved after the window will be closed, but you are able to download it via "File" -> "Download as" -> "Notebook (.ipynb) and then put it under version control, commit and push to GitHub, to make it available when you will launch the project on Binder next time. Alternatively, you can install Python and Jupyter on your computer and work with Jupyter notebooks locally.
For further information about Jupyter, see https://jupyter-notebook-beginner-guide.readthedocs.io/en/latest/index.html.
- When your project is ready for the release, make it citable by archiving it (with assigning a DOI) on the data archiving tool Zenodo (https://zenodo.org/), following instructions at https://guides.github.com/activities/citable-code/.