jupytoc 0.1.4

A commmand-line interface to add or update TOC to Jupyter Notebooks

<div align="center">
<img src="misc/logo.png" alt="jupytoc_logo"/>
</div>

<br/>

<div align="center">
<a href="https://badge.fury.io/py/jupytoc"><img src="https://badge.fury.io/py/jupytoc.svg" alt="PyPI version" height="18"></a>
<a href="https://requires.io/github/axelbellec/Jupytoc/requirements/?branch=master"><img src="https://requires.io/github/axelbellec/Jupytoc/requirements.svg?branch=master" alt="Requirements Status" /></a>
<a href="https://opensource.org/licenses/MIT">
<img src="http://img.shields.io/:license-mit-ff69b4.svg?style=flat-square" alt="mit"/>
</a>
<a href="https://travis-ci.org/axelbellec/jupytoc">
<img alt="Build Status" src="https://travis-ci.org/axelbellec/Jupytoc.svg?branch=master">
</a>
<a href='https://coveralls.io/github/axelbellec/Jupytoc?branch=master'><img src='https://coveralls.io/repos/github/axelbellec/Jupytoc/badge.svg?branch=master' alt='Coverage Status' /></a>
</div>

<br/>

<div align="center">
<p><b>Jupytoc</b> generates table of contents for jupyter notebook files. Links are compatible with anchors generated by GitHub.</p>
</div>

<br/>
<br/>

# `$ jupytoc`
:pushpin: A commmand-line interface to add/update/delete TOC to Jupyter Notebooks

## Usage

### Simplest usage

```sh
$ jupytoc <jupyter_notebook>
```

To add toc for all files in a directory, just launch:
```sh
$ jupytoc .
```

### CLI args/otps

```sh
$ jupytoc --help
Usage: jupytoc [OPTIONS] [NOTEBOOKS]...

Options:
-R, --recursive build TOC for all subdirectories recursively
-l, --maxlevel INTEGER limit TOC entries to headings only up to the
specified level
-t, --title TEXT custom TOC title
-s, --stdout print to stdout
-d, --delete remove TOC from notebook file
--help Show this message and exit.
```

### Adding (or update) TOC to all notebooks in a directory and sub directories

```sh
$ jupytoc .
```

### Custom TOC title

Use `--title` option to specify a custom TOC title (Markdown formatted).
e.g. :
```sh
$ jupytoc --title '**Contents**'
```

### Maximum heading level

Use `--maxlevel` option to limit TOC entries to a certain level.
By default, Jupyter Notebook headings are limited to 6 levels.

```sh
$ jupytoc --maxlevel 2
```

### Print generated TOC to stdout

Use `--stdout` flag to print to stdout.

```sh
$ jupytoc --stdout
```

### Deleting TOC

Use `--delete` option to delete a TOC.

```sh
$ jupytoc --delete <jupyter_notebook>
```

## Installation

### **1. PyPI**

```sh
$ pip install jupytoc
```

### **2. GitHub for the latest development version**

```sh
$ pip install git+https://github.com/axelbellec/jupytoc
```

Jupytoc has the following dependencies:

- [click](http://click.pocoo.org/6/): a command line library for Python
- [emoji](https://github.com/carpedm20/emoji/): emoji terminal output for Python

## Features

### Done

- [X] generate TOC a top of file
- [X] add/update an existing TOC in Markdown file
- [X] add/update TOC for all files in the current directory
- [X] handle multiple files input
- [X] limit TOC entries
- [X] add/udpate TOC to all files in a directory/sub directories
- [X] enable custom TOC title editing
- [X] print TOC to stdout
- [X] delete TOC option

### Still in development

- [ ] Test suite


## FAQ


__1. Why do my link anchors generated with `jupytoc` not work when the notebook is read on Github?__

GitHub rending concerning `.ipynb` notebooks do not let us to navigate through links.