NBDev template repository (with VSCode niceities)

Installation

You can clone this repo and use it as a template.

Once cloning it locally, run:

    $ ./bootstrap.sh

This installs requirements, the semi-official, but experimental nbdev VSCode extension, and nbdev git pre-commit hooks. You will be prompted for your sudo password because it installs Quarto, which needs root access by default. ¯\(ツ)/¯

Usage

Editing the README

1. To get started, open VSCode in this folder: code .
2. When prompted, install the workspace suggested extensions (like Python, Jupyter, etc)
3. Then, open the nbs/index.ipynb file in VSCode.
4. VSCode might likely prompt you to install Jupyter. That’s cool.
5. Edit the index.ipynb file, and watch as it automatically becomes your README.md when you run nbdev_build_docs.

To keep your docs updated as you edit your notebooks, run:

    $ ./scripts/nbdev_preview.sh

Editing the libraries:

The other notebooks automatically get converted to .py files when you run nbdev_build_lib.

1. To see how that works, open 00_core.ipynb.
2. run nbdev_build_lib to convert it to a .py file.
3. Open the nbdev_vscode_template/core.py file that was generated.
4. Put your cursor in the say_hello function and press F12 to jump to the definition of that function in your 00_core.ipynb file. (This is feature of the nbdev-vscode extension.)
5. Put your cursor in the add_one function in the notebook and hit F12 and see it jump to your function definition in the .py file.

Committing changes to git

This repository uses pre-commit hooks to cleanup the notebook before pushing.

Option 1: The simplest way to do things is to run this script to ensure that things are ready to be committed:

    ./scripts/nbdev_prepare.sh
    # Now git commit as always

Option 2: Rely upon pre-commit hooks:

When you do a git commit in this repo that has pre-commit hooks installed, your new workflow will be as follows:

1. pre-commit runs each hook on your staged changes (as in, changes that you git added)
2. If a hook changes files – for example, if a commited notebook wasn’t cleaned – pre-commit stops the commit, leaving those changes as unstaged. (This won’t happen if you use nbdev_prepare!)
3. You can now stage those changes and make any edits required to get pre-commit to pass
4. Redo the git commit, and if it succeeds, your commit will be created.
5. Using it in practice isn’t as complicated as it might sound. The best way to figure out if it works for you is to give it a try.

If you have questions, see this documentation about nbdev pre_commit

More details on nbdev:

For more on nbdev usage, follow the nbdev tutorial.

Github Actions

When you push changes to your github repo, you’ll see three actions run. (These actions are defined inside of .github/workflows)

1. test (this is the main CI step that runs each of your notebooks. A test is just a cell executing without an exception.)
2. Deploy to Github Pages (builds your Github pages to the gh-pages branch.)
3. pages-build-deployment (Automatically run when your gh-pages branch updates, to deploy your built pages to your site. )

If you want to see your Github pages hosted publicly, you’ll want to enable Github Pages in your repo settings.

Notebooks all the way down…

This README, just like everything else in nbdev, is authored in a notebook. That means we can do cool stuff like run code in the notebook, and have the output show up in the readme, like this:

say_hello("world")

'Hello world!'

Or this:

# Show an image of a cat:
from IPython.display import Image
Image(url="https://www.catster.com/wp-content/uploads/2017/08/A-fluffy-cat-looking-funny-surprised-or-concerned.jpg")

TODO

• Figure out how console scripts work in settings.ini and add bootstrap to that.
• Figure out the proper order of setup.py stuff and the bootstrap.sh stuff. (Should bootstrap.sh just be something that setup.py runs? I am a Python noob.)
• Show how to use https://github.com/benbalter/jekyll-auth to use private Github pages for private repos (without having to upgrade to Github Enterprise)
• When the NBDev-VSCode extension gets published, add it as a recommended extension.