v2.3 will be released soon-ish, and you can play with the upcoming functionality by installing from master. Here’s a summary of some of the key changes to know about.
The big change is that now rendering your docs is much faster. The time for the notebook processing stage for nbdev’s own notebooks has gone down from 24 seconds to 1 second! In addition, the latest quarto prerelease has also been sped up. The combination should dramatically cut your doc rendering time, possibly by even an order of magnitude!
The reason that nbdev’s notebook processing is faster is that we’ve written our own parallel processing system, instead of relying on quarto’s ipynb-filters. This system is automatically run whenever you call
nbdev_preview. It processes each of your notebooks, and places the result in a directory called
_proc in the root of your repo. These processed notebooks are exactly what quarto uses as input. Therefore, you can
cd into that directory and run
quarto publish, etc, and it’ll all “just work”. This is particularly useful if you use something other than Github Pages for publishing your docs, since
quarto publish supports numerous other services.
When you run
nbdev_preview, we now run our own watchdog server which watches for any changes, so you get live/hot reloading in the browser. Try changing and saving any notebook whilst preview is running, and you’ll see the results reflected in your browser immediately without any manual refresh required.
Previously, nbdev auto-generated your
_quarto.yml for you and updated it based on changes to
settings.ini. In v2.3 we still auto-generate it if it’s missing, but we no longer auto-update it. Instead, there’s a small
nbdev.yml that’s auto-updated from
settings.ini and is included into your
_quarto.yml. But other than that, you’re free to customise
_quarto.yml however you like, and your changes won’t ever get trampled by nbdev.
Previously, nbdev auto-generated your sidebar for you, assuming you had
custom_sidebar = True in your
settings.ini (which was the default). However, quarto (v1.2, currently in prerelease) now provides its own automatic sidebar system. Therefore, we’ll be deprecating
custom_sidebar = True, and you should switch to using Quarto’s approach. We’ll be providing a way to automate this change so most users won’t have to do anything manually except run a single line in the shell.
nbdev’s own docs are now using this approach, so take a look at the nbdev repo if you’re curious about how any of is working on the nbdev site.
PS: You may also be interested in checking out info about the changes in the v2.2 series.