Getting started#

Setup#

The first thing you’ll need to do is make a directory on your computer to hold your documentation pages:

$ mkdir my_docs
$ cd my_docs

If you’re used to Python development you’ll know there are a bunch of different ways to set up a project which uses Python tools. One way is to create a Python package which contains your tools as dependencies (i.e. a requirements.txt file or using something like Poetry). Another way is to install the tools you are using separately. We’ll go with the latter method here as you can use :program:`nbprett to develop any kind of documentation in any language.

We’ll use a tool called pipx to install our tools but you can use any method you like:

$ pipx install nbpretty

If we now go ahead and run the tool we’ll see something like:

$ nbpretty .
Usage: nbpretty [OPTIONS] DIRECTORY
Try 'nbpretty --help' for help.

Error: config.yaml could not be found

nbpretty is designed to be config-light, but there are some details that it needs before it can build anything, in this case it needs the name of the “book” that you are creating. This is specified in a file called config.yaml and just needs the following:

config.yaml#
---
course_title: My first course

We’re now ready to start writing the material.

Create your first page#

The pages in nbpretty are each written as Jupyter Notebooks so launch a JupyterLab interface in any way you’d like and create an empty notebook.

Save the notebook as 00 Introduction.ipynb. The leading numbers are used to order the pages, the space is important, and the rest of the file name is used to name the HTML output file and the title of the page.

If you now run nbpretty again, you’ll see something like:

$ nbpretty .
INFO     Constructing table of contents
INFO     Writing '00 Introduction.ipynb' as 'index.html'

So it’s used the lowest numbered file as the starting page for the book. You can go and open that file directly in a browser.

You’ll likely find it easier to use the --serve argument which will automatically open the generated HTML in a browser and rebuild it it when you make any changes:

$ nbpretty . --serve
INFO     Constructing table of contents
INFO     Writing '00 Introduction.ipynb' as 'index.html'
INFO     Serving on http://127.0.0.1:5500
INFO     Start watching changes
INFO     Start detecting changes
...

You should see a page open in your browser with the text “My first course” at the top, followed by the empty code cell in your notebook.

Try adding some markdown and code cells to the notebook and save it. You should see them appear in the generated page.

Add more pages#

Create a second notebook with the name 01 The Next Page.ipynb and make sure it’s saved.

If you look at the generated page now, you should see a “Next” link appeared at the bottom which takes you to the next page.

You can add as many pages you like in this same way. nbpretty will use the number in front of the title in the file name to order them. You can leave gaps in the numbering if you like, so you can have a 99 Summary.ipynb file which avoids renumbering as you develop your materials.

Table of contents#

You can add a book-wide table of contents to a page by creating an empty markdown cell and adding the toc tag to the cell.

Add one of these to the beginning of the 00 Introduction.ipynb notebook, and add a Markdown cell to the top of the 01 The Next Page.ipynb page containing:

# The next page

Make sure that both notebook are saved and you should see the table of contents appear on the first page.

Try adding some more pages and give each of those a title too. You will see the table of contents update as you go.

Exercises#

You will likely want to be able to set the students some exercises and it’s useful if these are highlighted. And Markdown cell can be tabbed with the exercise tag and it will show up specially in the output.

You can also literally put

### Exercise #

at the beginning of the Markdown cell and it will automatically number the exercises on each page.

Special page types#

nbpretty does not process every notebook file in the folder, only those that are named in a certain way. We’ve seen that it converts files named NN Title.ipynb but there are some other patterns that it converts.

One in particular that you might want is answer_foo.ipynb where “foo” can be anything you like. These will be processed and will create a corresponding answer_foo.html file.

These special pages will not be linked to automatically, but you can create a standard Markdown hyperlink to answer_foo.ipynb which will be converted to a link to answer_foo.html in the generated HTML.

Wrap-up#

This should be enough to get you started with nbpretty. Anything you can put in a notebook should work as you expect.