Skip to main content

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

Project description

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

<br/>

<div align="center">
<a href="https://badge.fury.io/py/jupyter"><img src="https://badge.fury.io/py/jupyter.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>
</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

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

jupytoc-0.0.4.tar.gz (4.8 kB view hashes)

Uploaded Source

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page