Skip to content

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
wants to merge 31 commits into
base: main
Choose a base branch
from
Open
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
31 commits
Select commit Hold shift + click to select a range
c93ea72
Add .qmd read functionality to processor
bhoov May 27, 2025
bf8c091
Fix file glob for nbdev to detect .qmd files as source nbs
bhoov May 28, 2025
fceff8f
Don't clean .qmd files
bhoov May 28, 2025
f113f14
Simplify `read_qmd` in style of nbdev code
bhoov May 28, 2025
3a8d61b
Allow custom directives in `.qmd` files
bhoov May 29, 2025
c7389eb
Attempt .qmd to generate good looking docs
bhoov May 29, 2025
c477249
Update sidebar.yml to look for .ipynb instead of .qmd in cache folder
bhoov May 30, 2025
82d3205
Execute .qmd files when rendering
bhoov May 30, 2025
b98f5ee
Cleanup function in succinct style of nbdev
bhoov May 30, 2025
6109227
Cleanup debugging statements
bhoov May 30, 2025
8a32180
Enable back-syncing qmd from changes in .py files
bhoov May 30, 2025
98f118d
Only use official frontmatter for .qmd documents
bhoov May 31, 2025
8b98a61
Add documentation for no custom YAML for qmd
bhoov May 31, 2025
d43cf36
Move qmd processing to 15_qmd.ipynb
bhoov May 31, 2025
adf7039
Allow .qmd frontmatter to still auto-calc title and description, but …
bhoov May 31, 2025
e025097
Create script to convert .ipynb to .qmd
bhoov May 31, 2025
19788db
Add script to convert ipynb to qmd
bhoov May 31, 2025
33ad5f1
Allow markdown after custom frontmatter
bhoov Jun 1, 2025
b124c76
Pre-compile fm regex
bhoov Jun 1, 2025
33a10cb
Improve converting from .ipynb to .qmd (account for backticks in pyth…
bhoov Jun 1, 2025
bdfb1db
.qmd files now read custom KV yaml
bhoov Jun 1, 2025
86354d9
Custom frontmatter now parsed correctly for docs
bhoov Jun 2, 2025
04c87d5
Cleanup frontmatter code
bhoov Jun 2, 2025
deebd53
Copy .qmd for docs
bhoov Jun 2, 2025
f49bd4b
Update nbs
bhoov Jun 2, 2025
90db296
Allow frontmatter keys to contain hyphens
bhoov Jun 2, 2025
c503fc4
Fix index.qmd not found
bhoov Jun 2, 2025
cb5a410
Initial draft of .qmd file tutorial
bhoov Jun 3, 2025
f27e408
Add annotations to custom functions
bhoov Jun 3, 2025
e510a85
Update tutorial
bhoov Jun 3, 2025
4f23ca8
Cleanup
bhoov Jun 3, 2025
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 0 additions & 1 deletion .gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -149,4 +149,3 @@ checklink/cookies.txt

# .gitconfig is now autogenerated
.gitconfig

140 changes: 140 additions & 0 deletions index.ipynb
Original file line number Diff line number Diff line change
@@ -0,0 +1,140 @@
{
"cells": [
{
"cell_type": "raw",
"metadata": {},
"source": [
"---\n",
"output-file: index.html\n",
"title: HAMUX\n",
"\n",
"---\n",
"\n"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"<!-- WARNING: THIS FILE WAS AUTOGENERATED! DO NOT EDIT! -->"
]
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {
"language": "python"
},
"outputs": [],
"source": [
"#| echo: false\n",
"# from hamux_qmd.core import *"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"> Energy formulation for deep learning\n",
"\n",
"This file will become your README and also the index of your documentation.\n",
"\n",
"## Developer Guide\n",
"\n",
"If you are new to using `nbdev` here are some useful pointers to get you started.\n",
"\n",
"### Install hamux_qmd in Development mode\n",
"\n",
"```sh\n",
"# make sure hamux_qmd package is installed in development mode\n",
"$ pip install -e .\n",
"\n",
"# make changes under nbs/ directory\n",
"# ...\n",
"\n",
"# compile to have changes apply to hamux_qmd\n",
"$ nbdev_prepare"
]
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {
"language": "python"
},
"outputs": [],
"source": [
"## Usage\n",
"\n",
"### Installation\n",
"\n",
"Install latest from the GitHub [repository][repo]:\n",
"\n",
"```sh\n",
"$ pip install git+https://github.com/bhoov/hamux_qmd.git"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"or from [conda][conda]\n",
"\n",
"```sh\n",
"$ conda install -c bhoov hamux_qmd"
]
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {
"language": "python"
},
"outputs": [],
"source": [
"or from [pypi][pypi]\n",
"\n",
"\n",
"```sh\n",
"$ pip install hamux_qmd"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"[repo]: https://github.com/bhoov/hamux_qmd\n",
"[docs]: https://bhoov.github.io/hamux_qmd/\n",
"[pypi]: https://pypi.org/project/hamux_qmd/\n",
"[conda]: https://anaconda.org/bhoov/hamux_qmd\n",
"\n",
"## How to use\n",
"\n",
"Fill me in please! Don't forget code examples:\n"
]
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {
"language": "python"
},
"outputs": [],
"source": [
"1+1"
]
}
],
"metadata": {
"kernelspec": {
"display_name": "Python 3",
"language": "python",
"name": "python3"
},
"language_info": {
"name": "python"
}
},
"nbformat": 4,
"nbformat_minor": 5
}
112 changes: 112 additions & 0 deletions index_ipynb.ipynb
Original file line number Diff line number Diff line change
@@ -0,0 +1,112 @@
{
"cells": [
{
"cell_type": "raw",
"metadata": {},
"source": [
"---\n",
"output-file: index_ipynb.html\n",
"title: HAMUX2\n",
"\n",
"---\n",
"\n"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"<!-- WARNING: THIS FILE WAS AUTOGENERATED! DO NOT EDIT! -->"
]
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {
"language": "python"
},
"outputs": [],
"source": [
"#| echo: false\n",
"# from hamux_qmd.core import *"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"> Energy formulation for deep learning\n",
"\n",
"This file will become your README and also the index of your documentation.\n",
"\n",
"## Developer Guide\n",
"\n",
"If you are new to using `nbdev` here are some useful pointers to get you started.\n",
"\n",
"### Install hamux_qmd in Development mode\n",
"\n",
"```sh\n",
"# make sure hamux_qmd package is installed in development mode\n",
"$ pip install -e .\n",
"\n",
"# make changes under nbs/ directory\n",
"# ...\n",
"\n",
"# compile to have changes apply to hamux_qmd\n",
"$ nbdev_prepare\n",
"```\n",
"\n",
"## Usage\n",
"\n",
"### Installation\n",
"\n",
"Install latest from the GitHub [repository][repo]:\n",
"\n",
"```sh\n",
"$ pip install git+https://github.com/bhoov/hamux_qmd.git\n",
"```\n",
"\n",
"or from [conda][conda]\n",
"\n",
"```sh\n",
"$ conda install -c bhoov hamux_qmd\n",
"```\n",
"\n",
"or from [pypi][pypi]\n",
"\n",
"\n",
"```sh\n",
"$ pip install hamux_qmd\n",
"```\n",
"\n",
"\n",
"[repo]: https://github.com/bhoov/hamux_qmd\n",
"[docs]: https://bhoov.github.io/hamux_qmd/\n",
"[pypi]: https://pypi.org/project/hamux_qmd/\n",
"[conda]: https://anaconda.org/bhoov/hamux_qmd\n",
"\n",
"## How to use\n",
"\n",
"Fill me in please! Don't forget code examples:"
]
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {
"language": "python"
},
"outputs": [],
"source": [
"1+1"
]
}
],
"metadata": {
"language_info": {
"name": "python"
}
},
"nbformat": 4,
"nbformat_minor": 2
}
37 changes: 34 additions & 3 deletions nbdev/_modidx.py
Original file line number Diff line number Diff line change
Expand Up @@ -100,7 +100,8 @@
'nbdev.frontmatter._dict2fm': ('api/frontmatter.html#_dict2fm', 'nbdev/frontmatter.py'),
'nbdev.frontmatter._fm2dict': ('api/frontmatter.html#_fm2dict', 'nbdev/frontmatter.py'),
'nbdev.frontmatter._insertfm': ('api/frontmatter.html#_insertfm', 'nbdev/frontmatter.py'),
'nbdev.frontmatter._md2dict': ('api/frontmatter.html#_md2dict', 'nbdev/frontmatter.py')},
'nbdev.frontmatter._md2dict': ('api/frontmatter.html#_md2dict', 'nbdev/frontmatter.py'),
'nbdev.frontmatter._parse_kv_block': ('api/frontmatter.html#_parse_kv_block', 'nbdev/frontmatter.py')},
'nbdev.imports': {},
'nbdev.maker': { 'nbdev.maker.ModuleMaker': ('api/maker.html#modulemaker', 'nbdev/maker.py'),
'nbdev.maker.ModuleMaker.__init__': ('api/maker.html#modulemaker.__init__', 'nbdev/maker.py'),
Expand Down Expand Up @@ -240,13 +241,21 @@
'nbdev.processors.strip_ansi': ('api/processors.html#strip_ansi', 'nbdev/processors.py'),
'nbdev.processors.strip_hidden_metadata': ( 'api/processors.html#strip_hidden_metadata',
'nbdev/processors.py')},
'nbdev.qmd': { 'nbdev.qmd._install_nbdev': ('api/qmd.html#_install_nbdev', 'nbdev/qmd.py'),
'nbdev.qmd': { 'nbdev.qmd._get_fence_ticks': ('api/qmd.html#_get_fence_ticks', 'nbdev/qmd.py'),
'nbdev.qmd._install_nbdev': ('api/qmd.html#_install_nbdev', 'nbdev/qmd.py'),
'nbdev.qmd._nb_to_qmd_str': ('api/qmd.html#_nb_to_qmd_str', 'nbdev/qmd.py'),
'nbdev.qmd._qmd_to_raw_cell': ('api/qmd.html#_qmd_to_raw_cell', 'nbdev/qmd.py'),
'nbdev.qmd.btn': ('api/qmd.html#btn', 'nbdev/qmd.py'),
'nbdev.qmd.div': ('api/qmd.html#div', 'nbdev/qmd.py'),
'nbdev.qmd.img': ('api/qmd.html#img', 'nbdev/qmd.py'),
'nbdev.qmd.ipynb_to_qmd': ('api/qmd.html#ipynb_to_qmd', 'nbdev/qmd.py'),
'nbdev.qmd.meta': ('api/qmd.html#meta', 'nbdev/qmd.py'),
'nbdev.qmd.read_nb_or_qmd': ('api/qmd.html#read_nb_or_qmd', 'nbdev/qmd.py'),
'nbdev.qmd.read_qmd': ('api/qmd.html#read_qmd', 'nbdev/qmd.py'),
'nbdev.qmd.tbl_row': ('api/qmd.html#tbl_row', 'nbdev/qmd.py'),
'nbdev.qmd.tbl_sep': ('api/qmd.html#tbl_sep', 'nbdev/qmd.py')},
'nbdev.qmd.tbl_sep': ('api/qmd.html#tbl_sep', 'nbdev/qmd.py'),
'nbdev.qmd.write_nb_or_qmd': ('api/qmd.html#write_nb_or_qmd', 'nbdev/qmd.py'),
'nbdev.qmd.write_qmd': ('api/qmd.html#write_qmd', 'nbdev/qmd.py')},
'nbdev.quarto': { 'nbdev.quarto.IndentDumper': ('api/quarto.html#indentdumper', 'nbdev/quarto.py'),
'nbdev.quarto.IndentDumper.increase_indent': ( 'api/quarto.html#indentdumper.increase_indent',
'nbdev/quarto.py'),
Expand Down Expand Up @@ -281,6 +290,27 @@
'nbdev.quarto.nbdev_sidebar': ('api/quarto.html#nbdev_sidebar', 'nbdev/quarto.py'),
'nbdev.quarto.prepare': ('api/quarto.html#prepare', 'nbdev/quarto.py'),
'nbdev.quarto.refresh_quarto_yml': ('api/quarto.html#refresh_quarto_yml', 'nbdev/quarto.py')},
'nbdev.read': { 'nbdev.read._apply_defaults': ('api/config.html#_apply_defaults', 'nbdev/read.py'),
'nbdev.read._basic_export_nb': ('api/config.html#_basic_export_nb', 'nbdev/read.py'),
'nbdev.read._cfg2txt': ('api/config.html#_cfg2txt', 'nbdev/read.py'),
'nbdev.read._fetch_from_git': ('api/config.html#_fetch_from_git', 'nbdev/read.py'),
'nbdev.read._get_info': ('api/config.html#_get_info', 'nbdev/read.py'),
'nbdev.read._git_repo': ('api/config.html#_git_repo', 'nbdev/read.py'),
'nbdev.read._has_py': ('api/config.html#_has_py', 'nbdev/read.py'),
'nbdev.read._nbdev_config_file': ('api/config.html#_nbdev_config_file', 'nbdev/read.py'),
'nbdev.read._prompt_user': ('api/config.html#_prompt_user', 'nbdev/read.py'),
'nbdev.read._type': ('api/config.html#_type', 'nbdev/read.py'),
'nbdev.read._xdg_config_paths': ('api/config.html#_xdg_config_paths', 'nbdev/read.py'),
'nbdev.read.add_init': ('api/config.html#add_init', 'nbdev/read.py'),
'nbdev.read.config_key': ('api/config.html#config_key', 'nbdev/read.py'),
'nbdev.read.create_output': ('api/config.html#create_output', 'nbdev/read.py'),
'nbdev.read.get_config': ('api/config.html#get_config', 'nbdev/read.py'),
'nbdev.read.is_nbdev': ('api/config.html#is_nbdev', 'nbdev/read.py'),
'nbdev.read.nbdev_create_config': ('api/config.html#nbdev_create_config', 'nbdev/read.py'),
'nbdev.read.show_src': ('api/config.html#show_src', 'nbdev/read.py'),
'nbdev.read.update_proj': ('api/config.html#update_proj', 'nbdev/read.py'),
'nbdev.read.update_version': ('api/config.html#update_version', 'nbdev/read.py'),
'nbdev.read.write_cells': ('api/config.html#write_cells', 'nbdev/read.py')},
'nbdev.release': { 'nbdev.release.Release': ('api/release.html#release', 'nbdev/release.py'),
'nbdev.release.Release.__init__': ('api/release.html#release.__init__', 'nbdev/release.py'),
'nbdev.release.Release._issue_groups': ('api/release.html#release._issue_groups', 'nbdev/release.py'),
Expand Down Expand Up @@ -365,4 +395,5 @@
'nbdev.sync.nbdev_update': ('api/sync.html#nbdev_update', 'nbdev/sync.py')},
'nbdev.test': { 'nbdev.test._keep_file': ('api/test.html#_keep_file', 'nbdev/test.py'),
'nbdev.test.nbdev_test': ('api/test.html#nbdev_test', 'nbdev/test.py'),
'nbdev.test.no_eval': ('api/test.html#no_eval', 'nbdev/test.py'),
'nbdev.test.test_nb': ('api/test.html#test_nb', 'nbdev/test.py')}}}
4 changes: 2 additions & 2 deletions nbdev/clean.py
Original file line number Diff line number Diff line change
Expand Up @@ -38,7 +38,7 @@ def nbdev_trust(
path = fname if fname.is_dir() else fname.parent
check_fname = path/".last_checked"
last_checked = os.path.getmtime(check_fname) if check_fname.exists() else None
nbs = globtastic(fname, file_glob='*.ipynb', skip_folder_re='^[_.]') if fname.is_dir() else [fname]
nbs = globtastic(fname, file_re=r'.*\.ipynb$|.*\.qmd$', skip_folder_re='^[_.]') if fname.is_dir() else [fname]
for fn in nbs:
if last_checked and not force_all:
last_changed = os.path.getmtime(fn)
Expand Down Expand Up @@ -141,7 +141,7 @@ def nbdev_clean(
_write = partial(process_write, warn_msg='Failed to clean notebook', proc_nb=_clean)
if stdin: return _write(f_in=sys.stdin, f_out=sys.stdout)
if fname is None: fname = get_config().nbs_path
for f in globtastic(fname, file_glob='*.ipynb', skip_folder_re='^[_.]'): _write(f_in=f, disp=disp)
for f in globtastic(fname, file_re=r'.*\.ipynb$', skip_folder_re='^[_.]'): _write(f_in=f, disp=disp) # Don't clean .qmd files

# %% ../nbs/api/11_clean.ipynb
def clean_jupyter(path, model, **kwargs):
Expand Down
8 changes: 4 additions & 4 deletions nbdev/doclinks.py
Original file line number Diff line number Diff line change
Expand Up @@ -116,20 +116,20 @@ def _build_modidx(dest=None, nbs_path=None, skip_exists=False):

# %% ../nbs/api/05_doclinks.ipynb
@delegates(globtastic)
def nbglob(path=None, skip_folder_re = '^[_.]', file_glob='*.ipynb', skip_file_re='^[_.]', key='nbs_path', as_path=False, **kwargs):
def nbglob(path=None, skip_folder_re = '^[_.]', file_re=r'.*\.ipynb$|.*\.qmd$', skip_file_re='^[_.]', key='nbs_path', as_path=False, **kwargs):
"Find all files in a directory matching an extension given a config key."
path = Path(path or get_config()[key])
recursive=get_config().recursive
res = globtastic(path, file_glob=file_glob, skip_folder_re=skip_folder_re,
res = globtastic(path, file_re=file_re, skip_folder_re=skip_folder_re,
skip_file_re=skip_file_re, recursive=recursive, **kwargs)
return res.map(Path) if as_path else res

# %% ../nbs/api/05_doclinks.ipynb
def nbglob_cli(
path:str=None, # Path to notebooks
symlinks:bool=False, # Follow symlinks?
file_glob:str='*.ipynb', # Only include files matching glob
file_re:str=None, # Only include files matching regex
file_glob:str=None, # Only include files matching glob
file_re:str=r'.*\.ipynb$|.*\.qmd$', # Only include files matching regex
folder_re:str=None, # Only enter folders matching regex
skip_file_glob:str=None, # Skip files matching glob
skip_file_re:str='^[_.]', # Skip files matching regex
Expand Down
Loading