Generates a navigable book-like structure to a collection of jupyter notebooks

# Archived

Due to naming collision with Binder, this packaged has been archived and is survived by the renamed version NBJoint.

## NBBinder - Jupyter Notebook Binder

NBBinder generates a navigable book-like structure to a collection of Jupyter notebooks.

## Description

The main function in this module is called bind(). It reads a collection of Jupyter notebooks from a given directory and, upon configuration,

• adds a badge cell to each notebook, with links to opening the notebooks in different platforms or formats. For instance, one can include a Google Colab badge and a Binder badge, with links to opening each notebook in these cloud computing plataforms, a badge for showing slides as exported with nbconvert, and so on.

• adds navigator links, at the beggining and at the end of each notebook, with links to traverse to the previous and the next notebook, and to other selected notebooks, such as the Table of Contents and the References;

• exports the notebooks to other formats using nbconvert, so that, for example, slides can be generated automatically and in bulk.

## Examples

### A little taste

For instance, upon proper configuration (see section Notebooks with slides and cloud computing badges below), the collection of bare notebooks in the folder Water bare collection is bound to the folder Water bound collection, and, in particular, the file 00.00-Water_Contents.ipynb receives a table of contents, a header, navigator cells and the badges

Below we show some examples in more details.

### Example with configuration file

The most convenient way to use the module, or script, is via a configuration file. The configuration files are written in the YAML format.

For instance, consider the following config_nb_alice.yml, which is included in the tests folder of the repository:

# Configuration file for the python module NBBinder

version: 0.13a

path_to_notes: nb_builds/nb_alice

contents:
show_index_in_toc: True

header: "NBBinder test on a collection of notebooks named after the chapters of 'Alice's Adventures in Wonderland'"

navigators:
core_navigators:
show_nb_title_in_nav: False
show_index_in_nav: False


#### Notebook collection

The following collection of indexed notebooks is included in the folder tests/nb_builds/nb_alice:

00.00-Alice's_Adventures_in_Wonderland.ipynb
01.00-Down_the_Rabbit-Hole.ipynb
02.00-The_Pool_of_Tears.ipynb
03.00-A_Caucus-Race_and_a_Long_Tale.ipynb
04.00-The_Rabbit_Sends_in_a_Little_Bill.ipynb
06.00-Pig_and_Pepper.ipynb
08.00-The_Queen's_Croquet-Ground.ipynb
09.00-The_Mock_Turtle's_Story.ipynb
11.00-Who_Stole_the_Tarts?.ipynb
12.00-Alice's_Evidence.ipynb


#### Binding the collection

One way to bind the collection of notebooks is to import the module and use the bind() function with this configuration file as argument:

import nbbinder as nbb
nbb.bind('config_nb_alice.yml')


Or we execute it as a script in the command line:

./nbbinder.py config_nb_alice.yml


In the tests directory, the configuration file is actually not in the same folder as the script. The collection is two folders down. This is indicated by the argument path_to_notes: nb_builds/nb_alice, given in the configuration file.

#### Result

After binding the notebooks in one of the two ways mentioned above, the following table of contents is inserted in the first notebook 00.00-Alice's_Adventures_in_Wonderland.ipynb:

Table of Contents
1. Down the Rabbit-Hole
2. The Pool of Tears
3. A Caucus-Race and a Long Tale
4. The Rabbit Sends in a Little Bill
6. Pig and Pepper
8. The Queen's Croquet-Ground
9. The Mock Turtle's Story
11. Who Stole the Tarts?
12. Alice's Evidence


See 00.00-Alice's_Adventures_in_Wonderland.ipynb for the actual bound version of the first notebook. Notice the header in the begining of the notebook and the navigator cells after the header and at the end of the notebook. Experiment with the navigator links to move to the other notebooks.

### Notebooks with subsections

By appropriately naming the files, we can have different formattings for the Table of Contents. For instance, if your list of files is

00.00-Front_Page.ipynb
01.00-Introduction.ipynb
02.00-Project_Requirements.ipynb
03.00-The_History_of_Grammar.ipynb
04.00-Parts_of_Speech.ipynb
04.01-Nouns.ipynb
04.02-Verbs.ipynb
05.00-Sentences.ipynb
05.01-Complex_Sentences.ipynb
05.02-Compound_Sentences.ipynb
06.00-Paragraphs.ipynb
06.01-Descriptive.ipynb
06.02-Expository.ipynb
06.03-Narrative.ipynb
06.04-Persuasive.ipynb
07.00-Conclusion.ipynb
A0.00-Appendix.ipynb
BA.00-Glossary.ipynb
BB.00-Bibliography.ipynb
BC.00-Index.ipynb


Table of Contents
Front Page
1. Introduction
2. Project Requirements
3. The History of Grammar
4. Parts of Speech
4.1. Nouns
4.2. Verbs
5. Sentences
5.1. Complex Sentences
5.2. Compound Sentences
6. Paragraphs
6.1. Descriptive
6.2. Expository
6.3. Narrative
6.4. Persuasive
7. Conclusion
A. Appendix
Glossary
Bibliography
Index


See 00.00-Front-Page.ipynb for the actual bound version of the first notebook.

The binder for the notebooks in this collection is configured to include badges to render, in nbviewer, either the Jupyter notebook itself or the exported version to markdown. The badge cell is located just below the header. Just click the badge with the mouse right button to open it. If clicking it with the right button, from within github, nothing will happen.

This is particularly useful for lectures notes. For instance, by naming your collection of notebooks as

00.00-Introduction.ipynb
01.00.Lecture-Math_Background.ipynb
01.01-Vector_Calculus.ipynb
01.02-Rigid_Motions.ipynb
02.00.Lecture-Kinematics.ipynb
02.01.Lecture-Velocity_and_Acceleration.ipynb
02.02.Lecture-Different_Types_of_Motions_and_Their_Components.ipynb
03.00.Lecture-Dynamics.ipynb
03.01..Part-Force_and_Momentum.ipynb
03.02..Part-Orbits_of_Planets_and_Satellites.ipynb
03.03..Part-Interception_and_Rendezvous.ipynb
04.00.Lecture-Trajectory_Optimization.ipynb
04.01.Lecture.Part-Performance.ipynb
04.02.Lecture.Part-Gravity_Turn.ipynb
04.03.Lecture.Part-Optimization.ipynb
AA.00-References.ipynb


Contents
Introduction
Lecture 1. Math Background
1.1. Vector Calculus
1.2. Rigid Motions
Lecture 2. Kinematics
Lecture 2.1. Velocity and Acceleration
Lecture 2.2. Different Types of Motions and Their Components
Lecture 3. Dynamics
Part 1. Force and Momentum
Part 2. Orbits of Planets and Satellites
Part 3. Interception and Rendezvous
Lecture 4. Trajectory Optimization
Lecture 4. Part 1. Performance
Lecture 4. Part 2. Gravity Turn
Lecture 4. Part 3. Optimization
References


See 00.00-Introduction.ipynb for the actual bound version of the first notebook.

Notice, above, different forms of displaying the parts of the same lecture note.

The binder for the notebooks in this collection is configured to include a badge to open them in nbviewer. The badge is located just below the header. Just click the badge with the mouse right button to open it. If clicking it with the right button, from within github, nothing will happen.

## Notebooks with slides and cloud computing badges

The following configuration file is used in the collection of files present in the folder Water:

# Configuration file for the python module NBBinder

version: 0.13a

path_to_notes: nb_builds/nb_water

contents:
toc_nb_name: 00.00-Water_Contents.ipynb
show_index_in_toc: True

header: "[*NBBinder test on a collection of notebooks about some thermodynamic properperties of water*](https://github.com/rmsrosa/nbbinder)"

navigators:
core_navigators:
- 00.00-Water_Contents.ipynb
- BA.00-References.ipynb
show_nb_title_in_nav: True
show_index_in_nav: False

- title: Open in Google Colab
- title: Open in binder
url: https://mybinder.org/v2/gh/rmsrosa/nbbinder/master?filepath=tests/nb_builds/nb_water
- title: View in NBViewer
url: https://nbviewer.jupyter.org/github/rmsrosa/nbbinder/blob/master/tests/nb_builds/nb_water
label: view in
message: nbviewer
color: orange
- title: View Slides
url: https://nbviewer.jupyter.org/github/rmsrosa/nbbinder/blob/master/tests/nb_builds/nb_water_slides
extension: .slides.html
label: view
message: slides
color: darkgreen

exports:
- export_path: nb_builds/nb_water_slides
exporter_name: slides
exporter_args:
reveal_scroll: True


After binding the collection, the folder Water bound collection is created. See 00.00-Water_Contents.ipynb for the first notebook, containing the table of contents. Now, each notebook has a badge cell with badges to open the notebooks in Google Colab, Binder, and nbviewer, and a final badge to open the associated Reveal.JS slides.

For the slides, the folder Water Slides is created via nbconvert, in accordance to the parameters associated with the key exports in the configuration file.

## Installation

The module is available in PyPI and installation is done with

pip install nbbinder


## Documentation

The documentation of NBBinder is hosted on nbbinder.readthedocs.io.

## Development

During the current alpha stage of the project, development is being done in the master branch, which is currently the only branch in the repository.

When the first beta version is released, the latest stable version will stay in the master branch and development will belong to a separate development branch.

## Maintainer

@rmsrosa

This work is based on a few scripts in Python Data Science Handbook/tools, which is considered as the original work, licensed by Jake VanderPlas under the MIT license.

See the file LICENSE in the root directory of the project.

## Project details

Uploaded source
Uploaded py3