This repository is an adaptable framework for publishing websites from Jupyter interactive notebooks.
Please copy and adapt this repository for your own project.
View the demo project website here.
If you find any problems, or would like to suggest new features, please open an Issue. We also encourage community contributions, e.g., by forking the repository, making your suggested changes, and issuing a pull request.
Copyright (c) 2017, Peter Carbonetto & Gao Wang.
All source code and software in this repository are made available under the terms of the MIT license.
To start your own Jupyter-notebook-based research website, please follow these steps.
Note: These instructions assume that you are managing your project files inside a git repository, but this is not strictly necessary; if you prefer not to do this, skip the git commands in the steps below. (For an introduction to git, see here or here.)
Install docker
. Double-check
after installation that docker
is properly installed, by typing:
docker run hello-world
# Hello from Docker.
# This message shows that your installation appears to be working correctly.
Pull the docker image that contains dependency software to generate the website:
docker pull gaow/jnbinder
Make a personal copy of this repository:
Download the latest release of this repository from Github.
Create a new git repository (git init ...
), copy all the files
from this repository to the new repository folder.
Change the working directory to the new repository folder and commit these files to the new repository:
git add ./
git commit
Alternatively, if you are not using git, create a new folder
(mkdir ...
) and add copy the files to this new folder.
Load the docker command to generate web-pages:
source jnbinder_docker.sh
After this, command prompt jnbinder
should be available from your terminal.
To verify, the following command should display the command interface:
jnbinder -h
Inside your new project directory, clean up and then re-generate all the webpages using the SoS release script:
jnbinder clean
jnbinder -s force
Important note: Building the webpages from the Jupyter
notebooks does not actually run the code in the notebooks. In fact
when executed from our docker
image the computation of your notebook
cannot be reproduced because the image does not have your computing environment
under which the notebooks are developed. If you
would like to run the code prior to generating the webpages, this
must be done interactively in Jupyter, or from the command line
using jupyter nbconvert --execute
.
All the webpages are created and stored in the "docs" directory. This is convenient for git repositories hosted on Github because Github Pages can be configured to publish the webpages from the "docs" folder.
View the newly generated home page docs/index.html
in your
favorite Web browser.
If you would like to upload your new git repository to a git hosting website, do the following:
Create a new empty repository on tour favorite git hosting website (e.g., Github, GitLab, Bitbucket. Currently, only Github has been tested; other sites may work as well, but may not support all the website publishing features.
Determine the URL of the host repository, and add this URL to the
repository on your computer with git remote add origin ...
.
Upload to the host repository with git push origin master
.
Configure the repository settings to publish the webpages; e.g., using Github Pages).
You are now ready to adapt the Jupyter-notebook-based website for your own project:
Modify the website settings by editing config.yml
. See the
comments in this file for more detailed instructions.
Copy, rename or delete the notebooks in the "analysis", "setup" and "license" directories.
Edit the notebooks interactively in Jupyter.
After you are satisfied with your changes, re-build the modified
webpages by running sos run release.sos
, or use
sos run release.sos -s force
to re-build all the webpages,
then commit your changes to the git repository.
Whenever you make global changes to the website (e.g., you change
the Boostrap theme in config.yml
), use the -s force
option to force
updates to all the webpages, not just the ones that have been modified.
The website is built by jnbinder
,
distributed as docker image gaow/jnbinder
.
jnbinder
does not make any formal releases. This repo releases / ships with
its latest stable version.
You can add option -j
to the command if you want to control the
number of parallel processes that generate the notebook. For example
-j 8
uses 8 processes.
The include_dir
setting in config.yml
specifies the project
subdirectories containing Jupyter notebooks to render into
webpages. If no index.ipynb
file is provided within a given
subdirectory, an index will automatically be generated that lists
links to all notebooks under that directory.
There is also the option of adding a table of contents to each
notebook by setting notebook_toc: True
in config.yml
.
For the table of contents and the automatically generated index, it
is recommended that the notebooks have descriptive names; e.g.,
Plot_station_map.ipynb
. All underscores are automatically treated
as spaces, so Plot_station_map.ipynb
will show as "Plot station
map" in the index file and table of contents.
So far, only the Cerulean, Flatly and Readable Bootstrap themes have been adapted and tested for this framework. It is possible to select other themes (see here for a larger collection), although they may not work as well. Also note that there may be style conflicts or inconsistencies in the included CSS files; please report these style conflicts by posting an Issue.
For more website customization details, please refer to the comments in the config.yml file.
ipynb website
was developed by:
Peter Carbonetto and Gao Wang
Dept. of Human Genetics
University of Chicago
John Blischak, Matthew Stephens and others have also contributed to the development of this software.