Skip to content
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.

Sign up for GitHub

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

auto-generate contribute.md from notebook #1497

Merged
merged 3 commits into from
Feb 24, 2025
Merged

auto-generate contribute.md from notebook #1497

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
f90a71d
feat: auto-generate contribute.md from nbs, re-add original contrib
bclavie Feb 24, 2025
5531feb
update style
bclavie Feb 24, 2025
2c15d52
nit: remove trailing newline
bclavie Feb 24, 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
4 changes: 3 additions & 1 deletion nbdev/_modidx.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -257,20 +257,22 @@
'nbdev.quarto._SidebarYmlRemoved.__init__': ( 'api/quarto.html#_sidebarymlremoved.__init__',
'nbdev/quarto.py'),
'nbdev.quarto._copytree': ('api/quarto.html#_copytree', 'nbdev/quarto.py'),
'nbdev.quarto._doc_mtime_not_older': ('api/quarto.html#_doc_mtime_not_older', 'nbdev/quarto.py'),
'nbdev.quarto._ensure_quarto': ('api/quarto.html#_ensure_quarto', 'nbdev/quarto.py'),
'nbdev.quarto._install_linux': ('api/quarto.html#_install_linux', 'nbdev/quarto.py'),
'nbdev.quarto._install_mac': ('api/quarto.html#_install_mac', 'nbdev/quarto.py'),
'nbdev.quarto._nbglob_docs': ('api/quarto.html#_nbglob_docs', 'nbdev/quarto.py'),
'nbdev.quarto._pre': ('api/quarto.html#_pre', 'nbdev/quarto.py'),
'nbdev.quarto._pre_docs': ('api/quarto.html#_pre_docs', 'nbdev/quarto.py'),
'nbdev.quarto._readme_mtime_not_older': ('api/quarto.html#_readme_mtime_not_older', 'nbdev/quarto.py'),
'nbdev.quarto._recursive_parser': ('api/quarto.html#_recursive_parser', 'nbdev/quarto.py'),
'nbdev.quarto._save_cached_contributing': ('api/quarto.html#_save_cached_contributing', 'nbdev/quarto.py'),
'nbdev.quarto._save_cached_readme': ('api/quarto.html#_save_cached_readme', 'nbdev/quarto.py'),
'nbdev.quarto._sort': ('api/quarto.html#_sort', 'nbdev/quarto.py'),
'nbdev.quarto._sprun': ('api/quarto.html#_sprun', 'nbdev/quarto.py'),
'nbdev.quarto.fs_watchdog': ('api/quarto.html#fs_watchdog', 'nbdev/quarto.py'),
'nbdev.quarto.install': ('api/quarto.html#install', 'nbdev/quarto.py'),
'nbdev.quarto.install_quarto': ('api/quarto.html#install_quarto', 'nbdev/quarto.py'),
'nbdev.quarto.nbdev_contributing': ('api/quarto.html#nbdev_contributing', 'nbdev/quarto.py'),
'nbdev.quarto.nbdev_docs': ('api/quarto.html#nbdev_docs', 'nbdev/quarto.py'),
'nbdev.quarto.nbdev_preview': ('api/quarto.html#nbdev_preview', 'nbdev/quarto.py'),
'nbdev.quarto.nbdev_proc_nbs': ('api/quarto.html#nbdev_proc_nbs', 'nbdev/quarto.py'),
Expand Down
3 changes: 2 additions & 1 deletion nbdev/cli.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -13,7 +13,7 @@
from .doclinks import *
from .test import *
from .clean import *
from .quarto import nbdev_readme, refresh_quarto_yml, fs_watchdog
from .quarto import nbdev_readme, nbdev_contributing, refresh_quarto_yml, fs_watchdog
from .export import nb_export
from .frontmatter import FrontmatterProc

Expand Down Expand Up @@ -121,6 +121,7 @@ def nbdev_new(**kwargs):
refresh_quarto_yml()
nbdev_export.__wrapped__()
nbdev_readme.__wrapped__()
nbdev_contributing.__wrapped__()

# %% ../nbs/api/13_cli.ipynb
mapping = {
Expand Down
41 changes: 38 additions & 3 deletions nbdev/quarto.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -21,7 +21,8 @@

# %% auto 0
__all__ = ['BASE_QUARTO_URL', 'install_quarto', 'install', 'IndentDumper', 'nbdev_sidebar', 'refresh_quarto_yml',
'nbdev_proc_nbs', 'nbdev_readme', 'nbdev_docs', 'prepare', 'fs_watchdog', 'nbdev_preview']
'nbdev_proc_nbs', 'nbdev_readme', 'nbdev_contributing', 'nbdev_docs', 'prepare', 'fs_watchdog',
'nbdev_preview']

# %% ../nbs/api/14_quarto.ipynb
def _sprun(cmd):
Expand Down Expand Up @@ -214,7 +215,7 @@ def nbdev_proc_nbs(**kwargs):
_pre_docs(**kwargs)[0]

# %% ../nbs/api/14_quarto.ipynb
def _readme_mtime_not_older(readme_path, readme_nb_path):
def _doc_mtime_not_older(readme_path, readme_nb_path):
if not readme_nb_path.exists():
print(f"Could not find {readme_nb_path}")
return True
Expand Down Expand Up @@ -259,14 +260,46 @@ def nbdev_readme(
"Create README.md from readme_nb (index.ipynb by default)"
cfg = get_config()
path = Path(path) if path else cfg.nbs_path
if chk_time and _readme_mtime_not_older(cfg.config_path/'README.md', path/cfg.readme_nb): return
if chk_time and _doc_mtime_not_older(cfg.config_path/'README.md', path/cfg.readme_nb): return

with _SidebarYmlRemoved(path): # to avoid rendering whole website
cache = proc_nbs(path)
_sprun(f'cd "{cache}" && quarto render "{cache/cfg.readme_nb}" -o README.md -t gfm --no-execute')

_save_cached_readme(cache, cfg)

# %% ../nbs/api/14_quarto.ipynb
def _save_cached_contributing(cache, cfg, contrib_nb):
"Move CONTRIBUTING.md (and any `_files` assets) from the Quarto build cache to the repo root."
tmp_doc_path = cache / cfg.doc_path.name
contrib_file = tmp_doc_path / 'CONTRIBUTING.md'
if contrib_file.exists():
final_path = cfg.config_path / 'CONTRIBUTING.md'
if final_path.exists(): final_path.unlink() # py37 doesn't have `missing_ok`
move(contrib_file, final_path)
assets_folder = tmp_doc_path / (Path(contrib_nb).stem + '_files') # Supporting files for CONTRIBUTING
if assets_folder.exists(): _copytree(assets_folder, cfg.config_path / assets_folder.name)

# %% ../nbs/api/14_quarto.ipynb
@call_parse
def nbdev_contributing(
path:str=None, # Path to notebooks
chk_time:bool=False # Only build if out-of-date
):
"""Create CONTRIBUTING.md from contributing_nb (defaults to 'contributing.ipynb' if present). Skips if the file doesn't exist."""
cfg = get_config()
path = Path(path) if path else cfg.nbs_path
contrib_nb_name = cfg.get('contributing_nb', 'contributing.ipynb')
contrib_nb_path = path / contrib_nb_name
if not contrib_nb_path.exists(): return
if chk_time and _doc_mtime_not_older(cfg.config_path / 'CONTRIBUTING.md' , contrib_nb_path): return

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

empty lines should only be added where needed to separate substantive sections

with _SidebarYmlRemoved(path): # to avoid rendering whole website
cache = proc_nbs(path)
_sprun(f'cd "{cache}" && quarto render "{cache/contrib_nb_name}" -o CONTRIBUTING.md -t gfm --no-execute')

_save_cached_contributing(cache, cfg, contrib_nb_name)

# %% ../nbs/api/14_quarto.ipynb
@call_parse
@delegates(_nbglob_docs)
Expand All @@ -277,6 +310,7 @@ def nbdev_docs(
"Create Quarto docs and README.md"
cache,cfg,path = _pre_docs(path, n_workers=n_workers, **kwargs)
nbdev_readme.__wrapped__(path=path, chk_time=True)
nbdev_contributing.__wrapped__(path=path, chk_time=True)
_sprun(f'cd "{cache}" && quarto render --no-cache')
shutil.rmtree(cfg.doc_path, ignore_errors=True)
move(cache/cfg.doc_path.name, cfg.config_path)
Expand All @@ -291,6 +325,7 @@ def prepare():
nbdev.clean.nbdev_clean.__wrapped__()
refresh_quarto_yml()
nbdev_readme.__wrapped__(chk_time=True)
nbdev_contributing.__wrapped__(chk_time=True)

# %% ../nbs/api/14_quarto.ipynb
@contextmanager
Expand Down
5 changes: 3 additions & 2 deletions nbs/api/13_cli.ipynb
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -38,7 +38,7 @@
"from nbdev.doclinks import *\n",
"from nbdev.test import *\n",
"from nbdev.clean import *\n",
"from nbdev.quarto import nbdev_readme, refresh_quarto_yml, fs_watchdog\n",
"from nbdev.quarto import nbdev_readme, nbdev_contributing, refresh_quarto_yml, fs_watchdog\n",
"from nbdev.export import nb_export\n",
"from nbdev.frontmatter import FrontmatterProc\n",
"\n",
Expand Down Expand Up @@ -222,7 +222,8 @@
"\n",
" refresh_quarto_yml()\n",
" nbdev_export.__wrapped__()\n",
" nbdev_readme.__wrapped__()"
" nbdev_readme.__wrapped__()\n",
" nbdev_contributing.__wrapped__()"
]
},
{
Expand Down
56 changes: 53 additions & 3 deletions nbs/api/14_quarto.ipynb
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -404,7 +404,7 @@
"outputs": [],
"source": [
"#|export\n",
"def _readme_mtime_not_older(readme_path, readme_nb_path):\n",
"def _doc_mtime_not_older(readme_path, readme_nb_path):\n",
" if not readme_nb_path.exists():\n",
" print(f\"Could not find {readme_nb_path}\")\n",
" return True\n",
Expand Down Expand Up @@ -482,7 +482,7 @@
" \"Create README.md from readme_nb (index.ipynb by default)\"\n",
" cfg = get_config()\n",
" path = Path(path) if path else cfg.nbs_path\n",
" if chk_time and _readme_mtime_not_older(cfg.config_path/'README.md', path/cfg.readme_nb): return\n",
" if chk_time and _doc_mtime_not_older(cfg.config_path/'README.md', path/cfg.readme_nb): return\n",
"\n",
" with _SidebarYmlRemoved(path): # to avoid rendering whole website\n",
" cache = proc_nbs(path)\n",
Expand Down Expand Up @@ -510,6 +510,54 @@
"# nbdev_readme.__wrapped__(chk_time=False)"
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "ef3f1e1f",
"metadata": {},
"outputs": [],
"source": [
"#|export\n",
"def _save_cached_contributing(cache, cfg, contrib_nb):\n",
" \"Move CONTRIBUTING.md (and any `_files` assets) from the Quarto build cache to the repo root.\"\n",
" tmp_doc_path = cache / cfg.doc_path.name\n",
" contrib_file = tmp_doc_path / 'CONTRIBUTING.md'\n",
" if contrib_file.exists():\n",
" final_path = cfg.config_path / 'CONTRIBUTING.md'\n",
" if final_path.exists(): final_path.unlink() # py37 doesn't have `missing_ok`\n",
" move(contrib_file, final_path)\n",
" assets_folder = tmp_doc_path / (Path(contrib_nb).stem + '_files') # Supporting files for CONTRIBUTING\n",
" if assets_folder.exists(): _copytree(assets_folder, cfg.config_path / assets_folder.name)"
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "729a0fa1",
"metadata": {},
"outputs": [],
"source": [
"#|export\n",
"@call_parse\n",
"def nbdev_contributing(\n",
" path:str=None, # Path to notebooks\n",
" chk_time:bool=False # Only build if out-of-date\n",
"):\n",
" \"\"\"Create CONTRIBUTING.md from contributing_nb (defaults to 'contributing.ipynb' if present). Skips if the file doesn't exist.\"\"\"\n",
" cfg = get_config()\n",
" path = Path(path) if path else cfg.nbs_path\n",
" contrib_nb_name = cfg.get('contributing_nb', 'contributing.ipynb')\n",
" contrib_nb_path = path / contrib_nb_name\n",
" if not contrib_nb_path.exists(): return\n",
" if chk_time and _doc_mtime_not_older(cfg.config_path / 'CONTRIBUTING.md' , contrib_nb_path): return\n",
" \n",
" with _SidebarYmlRemoved(path): # to avoid rendering whole website\n",
" cache = proc_nbs(path)\n",
" _sprun(f'cd \"{cache}\" && quarto render \"{cache/contrib_nb_name}\" -o CONTRIBUTING.md -t gfm --no-execute')\n",
" \n",
" _save_cached_contributing(cache, cfg, contrib_nb_name)"
]
},
{
"cell_type": "code",
"execution_count": null,
Expand All @@ -527,6 +575,7 @@
" \"Create Quarto docs and README.md\"\n",
" cache,cfg,path = _pre_docs(path, n_workers=n_workers, **kwargs)\n",
" nbdev_readme.__wrapped__(path=path, chk_time=True)\n",
" nbdev_contributing.__wrapped__(path=path, chk_time=True)\n",
" _sprun(f'cd \"{cache}\" && quarto render --no-cache')\n",
" shutil.rmtree(cfg.doc_path, ignore_errors=True)\n",
" move(cache/cfg.doc_path.name, cfg.config_path)"
Expand Down Expand Up @@ -559,7 +608,8 @@
" nbdev.test.nbdev_test.__wrapped__()\n",
" nbdev.clean.nbdev_clean.__wrapped__()\n",
" refresh_quarto_yml()\n",
" nbdev_readme.__wrapped__(chk_time=True)"
" nbdev_readme.__wrapped__(chk_time=True)\n",
" nbdev_contributing.__wrapped__(chk_time=True)"
]
},
{
Expand Down
1 change: 1 addition & 0 deletions settings.ini
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -40,6 +40,7 @@ console_scripts = nbdev_create_config=nbdev.config:nbdev_create_config
nbdev_preview=nbdev.quarto:nbdev_preview
nbdev_prepare=nbdev.quarto:prepare
nbdev_readme=nbdev.quarto:nbdev_readme
nbdev_contributing=nbdev.quarto:nbdev_contributing
nbdev_release_gh=nbdev.release:release_gh
nbdev_release_git=nbdev.release:release_git
nbdev_changelog=nbdev.release:changelog
Expand Down