Reflections on nbdev
as documentation
Trial run using
nbdev
for documentation only
My approach was to create a docs_src/
folder in my project root, import the code that I write using standard tools/test suites, and use nbdev just to generate the docs and examples that I want to deploy alongside my app.
I’m writing docs in .qmd
format to avoid the headache of jupyter+git+vim+AI assist in VSCode.
Pros/cons
Following are the pros/cons of switching to using nbdev
solely for the documentation instead of also for the code
Pros:
- I avoid a necessary “transpilation” step converting notebooks to python files every time I make a change to my code
- I can use VSCode’s excellent interactive python mode to develop my codebase
- I get to keep my
- Can use all nbdev goodies to make my executable documentation/test mix
- Can keep my code as a simple python file in the original repo
Cons:
- README of original repo is different than the
nbs/index.qmd
(nbd) - My docs/tests/code become scattered across my repo, some living in the documentation, others living in dedicated pytest files
- I don’t get the auto-generated
__all__
export