janpalasek / pretty-jupyter

Creates dynamic html report from jupyter notebook.

Pretty Jupyter

Simple package for beautiful & dynamic reports

Introduction

Pretty Jupyter is a package that creates beautifully styled and dynamic html webpage from Jupyter notebook.

Check out the demo and compare it with the default jupyter.

Main Features

• 👉 Visually appealing styles.
• 👉 Table of Contents can be automatically generated.
• 👉 Using Python variables in Markdown.
• 👉 Tabsets for hiding section content behind clickable tabs.
• 👉 Code Folding: Show/Hide code to filter out unnecessary content.
• 👉 Themes: Selection from a wide variaty of available themes.
• 👉 Wide range of configuration options with sensible defaults.
• 👉 Unobtrusive syntax that works well in notebook environments.

All these features are integrated directly in the output html page. Therefore there is no need for an interpreter running in the backend.

Installation

pip install pretty-jupyter

Usage

jupyter nbconvert --to html --template pj /path/to/ipynb/file

Resources

• Documentation
• Examples
• Cheat Sheet

Credits

• RMarkdown: RMarkdown served as a great inspiration when making this package.
• nbconvert: Pretty Jupyter uses nbconvert underhood. Its great extendability allowed this project to be created.

pretty-jupyter's Issues

Tabset

Problematic input:

# Header 1
### Tabset
[]: <> (-.- tabset)

#### Tab 1

#### Tab 2

## Chapter

The algorithm doesn't know that the tabset needs to end before Chapter section and not include it.

There might be some problematic counter examples, need to investigate.

Long tables

Long tables lead to overflow, which is currently hidden because useless scrollbar were appearing. The useless scrollbars appeared because the title is not in the main-container.

Solution: Move the title with header to main container and enable scrollbars for very long tables.

Note: Move the hide/show all button as well.

Add options to TOC

• Optional numbering of headers.
• Others picked from http://gregfranko.com/jquery.tocify.js/?

Allow to show errors and style it

Minimum version for nbconvert

Hi Jan,

It seems that your package depends on the new templating features of nbconvert introduced in nbconvert 6.0: described here

And it's not compatible with nbconvert 5.0 right? If so, I suggest adding in a minimum version to your package requirements.

any plan of adding 'plotly' support?

Hi,

awesome work, thank you for sharing this.
I wonder if you are planning to add interactive plot packages support? like R markdown knitted file. it supports plotly, highcharter and many interactive plotting packages.

thank you

Metadata

• Move metadata to a sub-attribute. Overriding will happen only on this sub-attribute.
• Print all metadata (except for reserved keywords) in meta tag.
• Print author, date and title. Change the page header to look better in this situation.

Generalize tokens

Currently the tokens ([//]: <> (-.- token1 token2) serve only for tabsets etc. It could be generalized to add classes or set ids for specified situations.

We can implement it this way: The token will add classes or ids to the previous element. This way, we could style markdown tables, markdown images, refs etc. and e.g. also disable default styling for tables.

• Implementation. Also add a different separator for future generalizations. When generating the token, generate token params to the insides of span to have greater power over the content.
• Testing. We need to create special selenium tests for this that will validate that even in weird situations it works. This functionality is prone to bugs, so it must be tested as well as possible.
• Docs.

Code inside Markdown

This does not get displayed correctly in the output HTML. However, it works without the details and summary tags.

<details>
<summary>...</summary>

```sql
select *
from tab1
where tab1.x = 10;

```

More examples for docs

Itables

Itables without initialization currently doesn't work.

Math mode

On some environment the mathjax url seems to be for some reason empty. Need to investigate. Possible solution: hardcode the version. This would work better to preserve the properties anyway. Similar thing is done to a lot of other utilities from R.

Class to avoid global JS changes

E.g. some styling is applied to all tables in the container. There should be possibility to avoid this. There should most likely be st like a class on the table that allows us to turn all styling off.

Section numbering

• Support unnumbered instead of toc-ignore for numbering. Edit command.

Test the visual appearance after generating the report

• Selenium?
• Something better?

<Tabsets> and <nbconvert --embed-images> can't be used together when exporting notebooks to html reports

Hello, Pretty Jupyter team,

Thank you for sharing this project and I really love the functionalities.

However, I think I found an issue that:

If I need to use the tabsets functionality, I can't use --embed-images in nbconvert when exporting, because using <--embed-images> will cause issues to the tabsets functionality.

Can you take a look at this issue? Many thanks!

Regards,
Chengfeng Liu

Frontend Pretty Jupyter tool with web-assembly

The description will be filled continously.

• Find out whether it is possible to create a simple frontend pretty jupyter tool: Accepts file, transforms using WA and outputs html file for download
  • Will pyodide support pretty-jupyter and nbconvert? Nbconvert likely yes, since there is a client-side jupyter JupyterLite.
  • Interoperation javascript + nbconvert.
• How to implement it? We likely cannot store file etc, we can just access it from javascript.
  • Will some changes be needed on pretty-jupyter's part?
• If it is possible, implement it.

Not-ended HTML tags

Sometimes when I do not end tags correctly, the report breaks:

E.g.: I've written this (notice nto correctly ended )

<details>
<summary><em>...<em></summary>
</details>

And both TOC and tabset stopped working.

This should be investigated and addressed.

Styles

Improve styles for:

• Code
• Error outputs.

Sphinx

Creating docs in sphinx and having it hosted on readthedocs would improve structuring, quality and versioning of the docs.

Button to download jupyter/open in colab?

Do you have any suggestions how this can be adapted to have a button to allow users to download the ipynb/open the ipynb in colab?

Tokens in code cells

Intro

Add support to tokens in code cells. This can be e.g. in jinja markdown or possibly other format too.

Analysis

Adding support for tokens in code cells would allow us e.g. to use only code cells and completely ignored md cells.

Example:

## Header
[//]: <> (-.- tabset)
We could write variable's value {{ variable }} such as this.

There is, however, one overarching problem: what to do with input cells. When we use code cell as a markdown, it provides no useful additional information. The user won't probably want to look at the code of the markdown with variables, there's no interesting information in there.

Therefore we want to (by default) hide those kind of input cells.

CI Fix

Problem with versions of chrome in selenium tests.

Cell-wise settings

We want to set up for each cell some kind of settings, such as: remove its output, input, stream outputs and stderr.
Decide what is the best way: celltags, or some other way?

Future work

• Link to stylesheet
• The execution order for each code cell
• Interpret author etc as a markdown. Allow html tags.
• Parametrize cell-level metadata.

Create templates

Move showing of all code to a better place

Embedding images

Thought it won't work, but it works. I'll add it to the tests.

Hide only some cells

Note: I think Jupyter supports this internally with cell metadata.

Allow override any notebook metadata setting from console

The goal is to enable users to override any notebook metadata from the command-line when generating the output. This will lead to a greater flexibility at no additional cost.

• Implementation.
• Testing.
• Docs.

Support for multiple tabset styles

Introduction

Tabset can have two types: tabset-pills and nav-tabs. Currently there is only pills supported. The goal of this issue is to support other tokens as well, such as these two.

Analysis

Currently the approach is to transform the tokens from md comment into html span elements with class contianing the tokens.

Ex: [//]: <> (-.- token1 token2) -> <span class="token1" display..></span><span class="token1" display..></span>

To process the tabset, javascript looks into the first

element after header containing with the appropriate tabset class.

This makes the inherent assumption that markdown wraps all the spans into paragraph, which might not be true. This depends on markdown processor.

More safe approach:

1. Create tokens as spans. We can ensure that the tokes will be unique by their name. We can add special class that makes the tokens easily searchable
   [//]: <> (-.- token1) -> <span class='pretty-jupyter-token token1' style='display: none;'></span>

2. One entire comment will lead to one span. This will be more resistant markdown -> html transformation. We need to change the markdown cell preprocessing to have the regex parse multiline etc.
   [//]: <> (-.- token1 token2) -> <span class='pretty-jupyter-token token1 token2' ...></span>

3. We need to have the javascript more resistant to the markdown processor. For tabset specifically, instead of searching headers, we can search for the elements and the closest wrapper div (e.g. with class pretty-jupyter-section, which we will add before by javascript), while still recommending in the documentation to have it right after the header.
   For example in the HTML above the algorithm would first identify the span with class pretty-jupyter-token and attribute tabset, also find out that the span has attribute tabset-pills and it would find the closest parent with class pretty-jupyter-section.

<div class="pretty-jupyter-section section level3">
  <h3>Some header</h3>
  <p><span class='pretty-jupyter-token tabset tabset-pills'></span></p>
</div>

Final transformation:

Original md:

### Some header
[//]: <> (-.- tabset tabset-pills)
[//]: <> (-.- some-token)

Into

Transformed md:

### Some header
<span class='pretty-jupyter-token tabset tabset-pills' ...></span><span class='pretty-jupyter-token some-token' ...></span>

<div class="pretty-jupyter-section section level3">
  <h3>Some header</h3>
  <p><span class='pretty-jupyter-token tabset tabset-pills' ...></span></p>
  <p><span class='pretty-jupyter-token some-token ...></span></p>
</div>

Note that the span must be hidden (display none).

Yaml metadata specification

Look at other jupyter project and decide whether it’s a good idea. Would it go along other such as papermill etc?
It might help reduce the pain of working with ipynb internal json structure, even though it is the usual way.

Remove not used imports

Goal is to remove js and css imports that are not used by Pretty Jupyter. Also some dependencies will be optional and it will be able to specify them in the notebook metadata.

Code cells style

Add optional dependencies

Add optional dependencies with the following functionality:

• matplotlib figure to embedded html, link html, link markdown (good for pdf)
• pandas to pageable html
• plotly to embedded image (no dynamic)
• ...

Dynamically created tabsets

Add themes

• Support for multiple themes.
• Add more themes to the base package.
• Allow to specify custom theme e.g. from url.
• Add example for themes and add it to docs.
• Link the themes as references (inside the file) and not embedded content. This will help in overriding the styles.
• Consider whether to force some different color that bootstraps red default for <code> element.
• Add new files to setup.py.
• Check performance.

jinja markdown shortcut

Since %%jinja markdown is potentially written in half of the cells, it would be nice to have some kind of shortcut. E.g. jmd.

pretty-jupyter compatible with SoS notebooks?

hello, i'm using sos notebooks in jupyter lab and it seems that %load_ext pretty_jupyter doesn't work in an sos kernel. Am I doing something wrong?

Tabsets do not work with $$ math mode

This is caused by jQuery function nextUntil ignoring text nodes, and:

$$a = 5$$ is exported in markdown into text node " $$a = 5$$ ".

2.0.0

• Change from json to yaml.
• Add option to turn off stdout and stderr. Add cell-level option too.
• Refactor NbMetadataPreprocessor. Add function is_input_enabled with parameters for notebook metadata, cell. Similarly is output enabled with parameters for notebook metadata, cell and output.
• Replace output_stderr with output_error that has both output_stderr and output.output_type == "error" inside.
• Add schema validation and other to nbmetadatapreprocessor.
• Test NbMetadataPreprocessor.
• Add new blocks to override to customize the page.
• Add testing of websites for many more notebooks than the one basic. Need to test functionality: TOC, Numbering sections, Tabs, classes to previous elements...
• Add support for version 7.0.0 of nbconvert. Problems found: removing input source
• Add new examples for metadata handling and interactive elements (plotly, itables). Update the current ones. Mainly extending the template will be different.
• Update all sections in documentation. Add changelog. Add section for metadata and configuration.
• Improve docs, improve readme.

Export to pdf

The export to pdf is not goal of this project. However if one chooses to do so, it would be good to at least do the following things:

• Hide Jinja Markdown input cells by default.
• Turn off code folding.
• Do not generate tabsets (ignore it).
• Don't generate table of contents (or generate a different one, mb future work).

The easiest way could be to create an inherited template jinja template for latex and then use pandoc as nbconvert probably does. Since nbconvert's template don't support tabsets etc, we wouldn't have to worry about it being set for pdf.

TODO:

• Configurations different for latex and html? Should be able to specify both in metadata. Some settings would be good to move to "html" section in metadata, e.g. code_folding, toc etc. They are usually left as a default by users anyway. Title, however, must stay where it is.

Errorneous table of content

Linkedin

• 1 Dataset
• 2 NER model
  • 2.1 Something
  • 2.2 Yes
    

Dataset

NER model

Something

Yes

Tried generating html with this using

jupyter nbconvert --template pj new_report.ipynb --to html

got weird toc like this:

Not properly nesting TOC

# Chapter 1
## Ignore 
[//]: # (-.- .toc-ignore)

## Not Ignore

# Chapter 2

jquery.tocify will output this as a list with one-level with three entries:

• Chapter 1
• Not Ignore
• Chapter 2

Instead of:

• Chapter 1
  • Not Ignore
• Chapter 2

The problem occurs only if the first subheader in the section is set as ignored.

How to bypass: The first subheader of a section must not have toc-ignore attribute.

How to design my own page header

Investigate blank space at the end

I am not sure if you call it an issue, but I think the generated html would look better without the blank space at the end.
Thank you again for your time and your package,
Best wishes

Originally posted by @chengfeng-liu in #67 (comment)

Code folding

Get inspired from Rmd styles to implement folding for:

• inputs with codes (wrap/unwrap)
• markdown (or jinja markdown) code sections

Update before Release

Update texts before release:

• README
• Examples on web-page
• Docs

Customising styles

Design an approach how to override and customise pages styles.

Test installation on Linux