Hi all, been a bit since I’ve written a post over here I absolutely love nbdev v2 and my creative juices are now flowing once again post the unconference As a result, I’m happy to introduce nbdev-extensions
pip install nbdev-extensions
This will serve as a conglomerate of various ideas I try out in nbdev, as an easy to use package for you
Currently there are two major features in it:
new_nb
One thing I find sometimes annoying is having to write out the boilerplate for new nbdev notebooks. This simple CLI interface let’s you create them on the fly, and customize them in any which way you’d like:
Arguably my favorite of the two extensions, Code Notes are a new annotation tool for, well, annotating code!
It works by having two cells, the first being a code cell with any code, and the following cell(s) be a markdown cell that contains a special #| explanation tag.
You specify what code should be highlighted, and the explanation that follows underneath (this can be anything, even LaTeX!), and then the documentation will render this as a two-part table. One tab will just have the code, and the second tab contains the explanations and code snippets you specified:
To develop your own processor plugin, sub-class Processor and override any methods you need to. Check out the nbdev.processors module for examples – all of nbdev’s processing is implemented with pluggable processors.
Once its ready, upload your package to PyPI and/or conda.
For example, the nbdev-extensions package provides the nbdev_extensions.codenotes.NoteExportProc processor, which allows you to annotate code snippets with a new #| explain directive.
Using a processor plugin
First install the package containing the processor. Continuing with the nbdev-extensions example which is hosted on PyPI:
pip install nbdev-extensions
Add the import path to your processor under the procs key of your settings.ini. The import path should follow the same syntax as setuptools console scripts (without the name and equals sign). For example:
procs = nbdev_extensions.codenotes:NoteExportProc
The processor will now be applied in your nbdev project!
@muellerzr Was very excited to use this today but ran into some problems. Mainly I couldn’t ever get it to create both the module entry and the title entry simultaneously. Only one or the other. Even when I simplly ran new_nb test it created a nb with a title but no module cell.
It might be important to note that I’m using Paperspace and I have added the following to my settings.ini :
BTW you should follow the in-progress guide here so you can turn this into an extension! (And can hook into something like nbdev_build_lib) Or just give guides on how to make it used jk just saw the other post
You might want to check out the nbdev-mkdocs, an extension of nbdev enabling you to use Material for Mkdocs for documentation generation. A tutorial and also an example can be found here:
Great. I’ve seen Material for Mkdocs many times but didn’t have the opportunity to go through it yet. Would you mind to share what are the important differences from your point of view (or pros/cons) wrt quarto? Had a look at your first page but didn’t find any comment about it?
Internally, we use Quarto to generate Markdown files and then generate documentation using Material for Mkdocs. Material for Mkdocs is probably the most popular tool for documentation for Python open-source projects, used by tools such as FastAPI and Pydantic. There is a large ecosystem of plugins for it and one such is automatic API Reference generation from docstrings, a very big selling point for us. I personally like look and feel of it, but that’s a question of taste.