-
Notifications
You must be signed in to change notification settings - Fork 507
Allow plain text .qmd
files as source notebooks
#1521
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Open
bhoov
wants to merge
31
commits into
AnswerDotAI:main
Choose a base branch
from
bhoov:qmd_support
base: main
Could not load branches
Branch not found: {{ refName }}
Loading
Could not load tags
Nothing to show
Loading
Are you sure you want to change the base?
Some commits from the old base branch may be removed from the timeline,
and old review comments may become outdated.
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Addresses #1461
Using quarto and its VS code extension, I find that writing
.qmd
files to be a smoother interactive alternative to.ipynb
files. That.qmd
files are plain text comes with several advantages:.qmd
seamlessly integrates with Cursor AI/other AI copilots..qmd
is fully compatible with standard git tooling.qmd
works better with VIM keybindings.qmd
files don't need a specialnbdev_clean
step to remove cell metadata and outputs, meaning your source files are not altered in any way by nbdev's transpilation process (something that bothers me immensely when developing in.ipynb
)Turns out,
nbdev
doesn't need many changes to implement this feature..qmd
in addition to .ipynbread_qmd
/write_qmd
function for converting the.qmd
to/from nbdev'sAttrDict
format. This means two-way sync (vianbdev_update
) also works for.qmd
and its corresponding.py
files.execnb
'srun_all
to generate outputs for the docs inside_proc/
-cached .ipynb files.It looks like there have been other attempts to allow .qmd support for nbdev (see this quarto issue) or allow plain-text support (see #1499). However, .qmd support is still missing in the current version of nbdev, and the latter seems to introduce additional dependencies without explicitly mentioning support for .qmd files. This PR allows you to seamlessly develop using a mix of
.qmd
and.ipynb
, whichever you prefer, with no additional dependencies.I've written up a small tutorial for setting good VSCode defaults in
nbs/tutorials/develop_in_plain_text.qmd
A few notes of caution and room for improvement:
00_core.ipynb
and00_core.qmd
, as both of these will create the intermediate_proc/00_core.ipynb
nbdev_prepare
will run executable cells in.qmd
documents twice: 1x when testing and, because outputs aren't saved, 1x when generating the docs.The PR is in a pretty stable position already (see this fork of nbdev rewritten entirely using
.qmd
files). There may be edge cases that I haven't considered, but in all I hope this is nearing a good shape to distribute.