numba / numba/numba-prototypes

Switch tutorial rendering to Jupyter Book (or something similar)

Open
#3 1 comment 0 reactions 0 assignees View on GitHub
Dominant language
HTML
Stars
8
Forks
6
PR merge metrics
No merged PRs in 30d

Description

The quick and simple notebook structure and rendering in #2 gets the job done, but requires manually creating an index notebook, and will struggle with things like cross-referencing later. Eventually we should switch to a tool that can handle generating the whole book and has these extra features.

Options include:
* [Jupyter Book](https://jupyterbook.org/en/stable/intro.html), which [supports Jupytext format sections](https://jupyterbook.org/en/stable/file-types/jupytext.html)
* [nbdev](https://nbdev.fast.ai/) New tool from Fast.ai that is specifically designed to generate software packages _and_ documentation from notebooks. This might be overkill, although I'm intrigued. Under the hood, it uses [Quarto](https://quarto.org/) to generate pages.

Contributor guide

No contributing guide indexed for this repository

Research direction

Start by reviewing the notebook structure and rendering introduced in #2. Compare Jupyter Book, nbdev, and Quarto against the stated needs, including Jupytext support and cross-referencing. Done means selecting and adopting a tool that generates the whole tutorial without a manually created index notebook.

Written by the indexing model from the issue text.

Assessment

Tech stack
jupyter, jupyter-notebook
Domain
documentation, tooling
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Stale
Clarity
Needs clarification
Newbie friendliness
25/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.