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.)

1. Install Python >= 3.6 and Jupyter. The recommended way to do this is to download and install Anaconda 3. Note that Python >= 3.6 comes with pip, so you should not need to install it separately.

2. Please also note: If you already have Jupyter installed for Python 2.x (e.g., Anaconda 2), or any other version of Python, then in the next step you will need to be careful that you install SoS for the same Python >= 3.6. In other words, you need Jupyter and SoS to be installed with the same Python >= 3.6. Run pip --version to make sure.)

   pip --version
   # pip 9.0.1 from /Users/pcarbo/anaconda3/lib/python3.6/site-packages (python 3.6)

3. Install SoS ("Script of Scripts") for Python 3.6:

   pip install sos-essentials

   Note that you may need to include the --user flag if you do not have administrative privileges on the computer.

   If you get a warning, "Could not find .egg-info directory in install record for sos...", please ignore it.

4. Install git.

5. At this point, you should have all the software you need to build webpages from the Jupyter notebooks. Please double-check this. For example, this is the setup on my MacBook Air with macOS 10.12.5:

   which python; python --version
   # /Users/pcarbo/anaconda3/bin/python
   # Python 3.6.1 :: Anaconda 4.4.0 (x86_64)
   which jupyter; jupyter --version
   # /Users/pcarbo/anaconda3/bin/jupyter
   # 4.3.0
   which sos; sos --version
   # /Users/pcarbo/anaconda3/bin/sos
   # sos 0.9.10.16 for Python 3.6.1
   which git; git --version
   $ which git; git --version
   # /usr/bin/git
   # git version 2.9.3 (Apple Git-75)

6. 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.

7. Inside your new project directory, clean up and then re-generate all the webpages using the SoS release script:

   sos run release.sos clean
   sos run release.sos -s force

   Or, simply:

   ./release.sos clean
   ./release.sos -s force

   if release.sos is granted executable permission.

   Important note: Building the webpages from the Jupyter notebooks does not actually run the code in the notebooks. 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.

8. View the newly generated home page docs/index.html in your favorite Web browser.

9. 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).

10. 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 which does not make any formal releases. This repo releases / ships with its latest stable version.

  To upgrade jnbinder to its latest, type:

  ./release.sos upgrade-jnbinder
  

  If you are on version < 0.9.2 you need to run this command twice to upgrade:

   ./release.sos upgrade-jnbinder  
   ./release.sos upgrade-jnbinder
  

• 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.