nb

package module
v0.2.1 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jan 30, 2024 License: MIT Imports: 5 Imported by: 3

README ΒΆ

nb

Build status Go Reference Go Report Card codecov

Render Jupyter Notebooks in pure Go πŸ“”

This package is inspired by @yuin's goldmark and is designed to be as clear and extensible.

The implementation follows the official Jupyter Notebook format spec (nbformat) and produces an output similar to that of nbconvert (Jupyter's team own reference implementation) both structurally and visually.

Although the current release only supports v4.4 notebooks, support for other formats will be added soon (see the Roadmap).
The package comes with an HTML renderer out of the box and can be extended to convert notebooks to other formats, such as LaTeX or PDF.

πŸ— This package is being actively developed: its structure and APIs might change overtime.
If you find any bugs, please consider opening an issue or submitting a PR.

Installation

go get github.com/bevzzz/nb

Usage

nb's default, no-frills converter can render markdown, code, and raw cells out of the box:

b, err := os.ReadFile("notebook.ipynb")
if err != nil {
	panic(err)
}
err := nb.Convert(os.Stdout, b)

To produce richer output nb relies on a flexible extension API and a collection of built-in adapters and standalone extensions that allow using other packages to render parts of the notebook:

import (
	"github.com/bevzzz/nb"
	synth "github.com/bevzzz/nb-synth"
	"github.com/bevzzz/nb/extension"
	"github.com/bevzzz/nb/extension/adapter"
	jupyter "github.com/nb/extension/extra/goldmark-jupyter"
	"github.com/robert-nix/ansihtml"
	"github.com/yuin/goldmark"
	highlighting "github.com/yuin/goldmark-highlighting/v2"
	
)

md := goldmark.New(
	goldmark.WithExtensions(
		jupyter.Attachments(),
		highlighting.Highlighting,
	),
)

c := nb.New(
	nb.WithExtensions(
		jupyter.Goldmark(md),
		synth.Highlighting,
		extension.NewStream(
			adapter.AnsiHtml(ansihtml.ConvertToHTML),
		),
	),
)

err := nb.Convert(os.Stdout, b)

The snippet above uses these additional dependencies which I encourage you to check out:

Extending nb does not end here. Your project may already use a different Markdown renderer, or require custom handling of certain mime-/cell types, in which case I hope the existing extensions will serve as useful reference implementations.

Styling the notebook: batteries included πŸ”‹

nb comes with the Jupyter's classic light theme, which you can capture by passing a dedicated CSSWriter and adding it to the final HTML.

Mind that the default theme is ~1000 lines long and might not fit the existing style in a more complex project.
In that case you probably want to write your own CSS.

Click to expand 
// Write both CSS and notebook's HTML to intermediate destinations
var body, css bytes.Buffer

// Configure your converter
c := nb.New(
  	nb.WithRenderOptions(
		render.WithCellRenderers(
			html.NewRenderer(
				html.WithCSSWriter(&css),
			),
		),
	),
)

err := c.Convert(&body, b)
if err != nil {
	panic(err)
}

// Create the final output
f, _ := os.OpenFile("notebook.html", os.O_RDWR, 0644)
defer f.Close()

f.WriteString("<html><head><style>")
io.Copy(f, &css)
f.WriteString("</style></head>")

f.WriteString("<body>")
io.Copy(f, &body)
f.WriteString("</body></html>")

Roadmap πŸ—Ί

  • v0.3.0:
    • Support for older nbformat versions:
      • v4.*
      • v3.0
      • v2.0
    • Custom CSS (class prefix / class names). I really the way chroma exposes its styling API and I'll try to do something similar.
  • v0.4.0:
    • Support for v1.0 notebooks
    • Built-in pretty-printing for JSON outputs
  • Other:
    • I am curious about how nb's performance measures against other popular libraries like nbconvert (Python) and quarto (Javascript), so I want to do some benchmarking later.
    • As of now, I am not planning on adding converters to other formats (LaTeX, PDF, reStructuredText), but I will gladly consider this if there's a need for those.

If you have any other ideas or requests, please feel welcome to add a proposal in a new issue.

Miscellaneous

Math

Since Jupyter notebooks are often used for scientific work, you may want to display mathematical notation in your output.
MathJax is a powerful tool for that and adding it to your HTML header is the simplest way to get started.

Notice, that we want to remove <pre> from the the list of skipped tags, as default HTML renderer will wrap raw and markdown cells in a <pre> tag.

<html>
	<head>
		<script>
		    MathJax = {
		      options: {
		        skipHtmlTags: [ // includes "pre" by default
			        "script",
			        "noscript",
			        "style",
			        "textarea",
			        "code",
			        "annotation",
			        "annotation-xml"
			    ],
		      }
		    };
		</script>
	</head>
</html>

MathJax is very configurable and you can read more about that here.
You may also find the official MathJax config used in the Jupyter project useful.

License

This software is released under the MIT License.

Documentation ΒΆ

Index ΒΆ

Constants ΒΆ

This section is empty.

Variables ΒΆ

This section is empty.

Functions ΒΆ

func Convert ΒΆ 

func Convert(w io.Writer, source []byte) error

Convert a Jupyter notebook using default converter.

func DefaultRenderer ΒΆ 

func DefaultRenderer() render.Renderer

DefaultRenderer configures an HTML renderer.

func Version ΒΆ 

func Version() string

Version returns current release version.

Types ΒΆ

type Converter ΒΆ 

type Converter interface {
	Convert(w io.Writer, source []byte) error
}

Converter converts raw Jupyter Notebook JSON to the selected format.

type Extension ΒΆ added in v0.2.0 

type Extension interface {
	Extend(n *Notebook)
}

Extension adds new capabilities to the base Notebook.

type Notebook ΒΆ 

type Notebook struct {
	// contains filtered or unexported fields
}

Notebook is an extensible Converter implementation.

func New ΒΆ 

func New(opts ...Option) *Notebook

New returns a converter with default HTML renderer and extensions.

func (*Notebook) Convert ΒΆ 

func (n *Notebook) Convert(w io.Writer, source []byte) error

Π‘onvert raw Jupyter Notebook JSON and write the output.

func (*Notebook) Renderer ΒΆ added in v0.2.0 

func (n *Notebook) Renderer() render.Renderer

Renderer exposes current renderer, allowing it to be further configured and/or extended.

type Option ΒΆ 

type Option func(*Notebook)

func WithExtensions ΒΆ added in v0.2.0 

func WithExtensions(exts ...Extension) Option

WithExtensions adds extensions.

func WithRenderOptions ΒΆ 

func WithRenderOptions(opts ...render.Option) Option

WithRendererOptions adds configuration to the current notebook renderer.

func WithRenderer ΒΆ 

func WithRenderer(r render.Renderer) Option

WithRenderer sets a new notebook renderer. Set this option before passing any WithRenderOptions.

Source Files ΒΆ

View all Source files

Directories ΒΆ

Path Synopsis
example
nbee module
adapter
Package adapter provides convenient adapters for other popular packages making it simple to use those as nb extensions.
 Package adapter provides convenient adapters for other popular packages making it simple to use those as nb extensions.
extra/goldmark-jupyter module
pkg
test
Package test provides test doubles that implement some of nb interfaces.
 Package test provides test doubles that implement some of nb interfaces.
html
internal/wildcard
Package wildcard implements simple pattern matching for strings with wildcard characters.
 Package wildcard implements simple pattern matching for strings with wildcard characters.
common
v4

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.