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.