Nbdev

Here is our main process using nbdev

Create a new project

Create a new GitHub project with Poetry for dependency management (or using pip)
Create the .gitignore file
Install Nbdev

poetry install
poetry shell
poetry add nbdev --group dev
nbdev_install_quarto
poetry add jupyterlab-quarto --group dev

Initiate Nbdev project

nbdev_new

PyPi library name can’t have _ while repo path can’t have -.

nbdev_new assumes that your package name is the same as your repo name (with - replaced by _). Use the --lib_name option if that isn’t the case.

So lib_name can be nbdev-cards and the lib_path can be nbdev_cards. If encountering No module named 'pkg_resources' error, do poetry add setuptools (or pip install setuptools).

Do a poetry install # this is in lieu of pip install -e . and this needs to be done only once

Develop the project

nbdev_export will convert notebook to modules.
nbdev_docs to update docs including the README
nbdev_preview initiates a server to display documentation
nbdev_readm render the README
nbdev_test to run local tests defined in the notebook
nbdev_pypi to publish to PyPI

nbdev_prepare, to run the nbdev_export, nbdev_clean, nbdev_test, nbdev_readme all together, useful before we push changes.

Then

git status
git commit -am "update"
git push

Consider using pre-commit hook to make notebook version control cleaner. If the hook processing fails and modifies the file, we need to add the modifications into commit, and then it will pass! Do git add -u and commit again again will do the trick!
Consider use various methods in fastcore.test module for tests.

What goes to where (doc vs. module)

To add the cell to the module file, use #| export
To use the cell for development only, without it exposing to module and docs, use #| hide, this is useful, e.g., for inline tests that don’t need to be in the doc.
To show documentation for class, for a class cell with #| export, its signature will automatically appear in the docs. But the methods inside will NOT.
To show documentation for methods, we can define them in their own cells and then use show_doc(method_name). For methods that belong to a class, use@patch`. For static methods, use:

@staticmethod
@patch_to(Class)

If a cell has neither #| export nor #| hide, it will still appear in the doc in its literal form.

Misc tips

From time to time, restart, and run all cells. Restart the Jupyter kernel after making changes to dependent modules.
For debugging, simply add a new cell and put %debug, note that the pop up window is on the top portion of the VScode Window.
Suspend and put into background ^Z, bg
Assert not level error when running nbdev_export: Make sure all the import statements in all notebooks under “nbs” folder are valid. If necessary, moving the ones that are not working to check.
if nbdev_docs raises error and things get cluttered, try to delete the _docs and _proc directories and re-run.
Still encounter Nbdev_export SyntaxError from time to time, made a check_syntax gist to solve it.