Refactor quarto.nbdev_readme; add docs

Author: hugetim

nbdev/_modidx.py

@@ -231,13 +231,20 @@
                            'nbdev.qmd.meta': ('api/qmd.html#meta', '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.quarto': { 'nbdev.quarto._copytree': ('api/quarto.html#_copytree', 'nbdev/quarto.py'),
+            'nbdev.quarto': { 'nbdev.quarto.SidebarYmlRemoved': ('api/quarto.html#sidebarymlremoved', 'nbdev/quarto.py'),
+                              'nbdev.quarto.SidebarYmlRemoved.__enter__': ( 'api/quarto.html#sidebarymlremoved.__enter__',
+                                                                            'nbdev/quarto.py'),
+                              'nbdev.quarto.SidebarYmlRemoved.__exit__': ('api/quarto.html#sidebarymlremoved.__exit__', 'nbdev/quarto.py'),
+                              'nbdev.quarto.SidebarYmlRemoved.__init__': ('api/quarto.html#sidebarymlremoved.__init__', 'nbdev/quarto.py'),
+                              'nbdev.quarto._copytree': ('api/quarto.html#_copytree', '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_not_out_of_date': ('api/quarto.html#_readme_not_out_of_date', '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.py

@@ -1,6 +1,6 @@
 # AUTOGENERATED! DO NOT EDIT! File to edit: ../nbs/api/14_quarto.ipynb.
 
-# %% ../nbs/api/14_quarto.ipynb 2
+# %% ../nbs/api/14_quarto.ipynb 3
 from __future__ import annotations
 import subprocess,sys,shutil,ast,warnings,traceback
 from os import system
@@ -18,14 +18,14 @@
 
 # %% auto 0
 __all__ = ['BASE_QUARTO_URL', 'install_quarto', 'install', 'nbdev_sidebar', 'refresh_quarto_yml', 'nbdev_proc_nbs',
-           'nbdev_readme', 'nbdev_docs', 'prepare', 'fs_watchdog', 'nbdev_preview']
+           'SidebarYmlRemoved', 'nbdev_readme', 'nbdev_docs', 'prepare', 'fs_watchdog', 'nbdev_preview']
 
-# %% ../nbs/api/14_quarto.ipynb 4
+# %% ../nbs/api/14_quarto.ipynb 5
 def _sprun(cmd):
     try: subprocess.check_output(cmd, shell=True)
     except subprocess.CalledProcessError as cpe: sys.exit(cpe.returncode)
 
-# %% ../nbs/api/14_quarto.ipynb 6
+# %% ../nbs/api/14_quarto.ipynb 7
 BASE_QUARTO_URL='https://www.quarto.org/download/latest/'
 
 def _install_linux():
@@ -50,15 +50,15 @@ def install_quarto():
         elif 'linux' in sys.platform: _install_linux()
     finally: system('sudo rm -f .installing')
 
-# %% ../nbs/api/14_quarto.ipynb 7
+# %% ../nbs/api/14_quarto.ipynb 8
 @call_parse
 def install():
     "Install Quarto and the current library"
     install_quarto.__wrapped__()
     d = get_config().lib_path
     if (d/'__init__.py').exists(): system(f'pip install -e "{d.parent}[dev]"')
 
-# %% ../nbs/api/14_quarto.ipynb 9
+# %% ../nbs/api/14_quarto.ipynb 10
 def _pre(p,b=True): return '    ' * (len(p.parts)) + ('- ' if b else '  ')
 def _sort(a):
     x,y = a
@@ -75,7 +75,7 @@ def _nbglob_docs(
     **kwargs):
     return nbglob(path, file_glob=file_glob, file_re=file_re, **kwargs)
 
-# %% ../nbs/api/14_quarto.ipynb 10
+# %% ../nbs/api/14_quarto.ipynb 11
 @call_parse
 @delegates(_nbglob_docs)
 def nbdev_sidebar(
@@ -108,7 +108,7 @@ def _f(a,b): return Path(a),b
     if printit: return print(yml)
     yml_path.write_text(yml)
 
-# %% ../nbs/api/14_quarto.ipynb 13
+# %% ../nbs/api/14_quarto.ipynb 14
 _quarto_yml="""project:
   type: website
 
@@ -130,7 +130,7 @@ def _f(a,b): return Path(a),b
 
 metadata-files: [nbdev.yml, sidebar.yml]"""
 
-# %% ../nbs/api/14_quarto.ipynb 14
+# %% ../nbs/api/14_quarto.ipynb 15
 _nbdev_yml="""project:
   output-dir: {doc_path}
 
@@ -142,7 +142,7 @@ def _f(a,b): return Path(a),b
   repo-url: "{git_url}"
 """
 
-# %% ../nbs/api/14_quarto.ipynb 15
+# %% ../nbs/api/14_quarto.ipynb 16
 def refresh_quarto_yml():
     "Generate `_quarto.yml` from `settings.ini`."
     cfg = get_config()
@@ -156,13 +156,13 @@ def refresh_quarto_yml():
     if qy.exists() and not str2bool(cfg.get('custom_quarto_yml', True)): qy.unlink()
     if not qy.exists(): qy.write_text(_quarto_yml)
 
-# %% ../nbs/api/14_quarto.ipynb 16
+# %% ../nbs/api/14_quarto.ipynb 17
 def _ensure_quarto():
     if shutil.which('quarto'): return
     print("Quarto is not installed. We will download and install it for you.")
     install.__wrapped__()
 
-# %% ../nbs/api/14_quarto.ipynb 17
+# %% ../nbs/api/14_quarto.ipynb 18
 def _pre_docs(path=None, n_workers:int=defaults.cpus, **kwargs):
     cfg = get_config()
     path = Path(path) if path else cfg.nbs_path
@@ -174,55 +174,66 @@ def _pre_docs(path=None, n_workers:int=defaults.cpus, **kwargs):
     cache = proc_nbs(path, n_workers=n_workers, **kwargs)
     return cache,cfg,path
 
-# %% ../nbs/api/14_quarto.ipynb 18
+# %% ../nbs/api/14_quarto.ipynb 19
 @call_parse
 @delegates(proc_nbs)
 def nbdev_proc_nbs(**kwargs):
     "Process notebooks in `path` for docs rendering"
     _pre_docs(**kwargs)[0]
 
-# %% ../nbs/api/14_quarto.ipynb 20
+# %% ../nbs/api/14_quarto.ipynb 21
+def _readme_not_out_of_date(readme_path, readme_nb_path):
+    if not readme_nb_path.exists():
+        print(f"Could not find {readme_nb_path}")
+        return True
+    return readme_path.exists() and readme_path.stat().st_mtime>=readme_nb_path.stat().st_mtime
+
+# %% ../nbs/api/14_quarto.ipynb 22
+class SidebarYmlRemoved:
+    def __init__(self,path): self._path=path
+    def __enter__(self):
+        self._yml_path = self._path/'sidebar.yml'
+        self._moved=False
+        if self._yml_path.exists():
+            self._yml_path.rename(self._path/'sidebar.yml.bak')
+            self._moved=True
+    def __exit__(self, exc_type, exc_value, exc_tb):
+        if self._moved: (self._path/'sidebar.yml.bak').rename(self._yml_path)
+
+# %% ../nbs/api/14_quarto.ipynb 23
 def _copytree(a,b):
     if sys.version_info.major >=3 and sys.version_info.minor >=8: copytree(a, b, dirs_exist_ok=True)
     else:
         from distutils.dir_util import copy_tree
         copy_tree(a, b)
 
-# %% ../nbs/api/14_quarto.ipynb 21
+# %% ../nbs/api/14_quarto.ipynb 24
+def _save_cached_readme(cache, cfg):
+    tmp_doc_path = cache/cfg.doc_path.name
+    readme = tmp_doc_path/'README.md'
+    if readme.exists():
+        readme_path = cfg.config_path/'README.md'
+        if readme_path.exists(): readme_path.unlink() # py37 doesn't have `missing_ok`
+        move(readme, cfg.config_path)
+        _rdmi = tmp_doc_path/((cache/cfg.readme_nb).stem + '_files') # Supporting files for README
+        if _rdmi.exists(): _copytree(_rdmi, cfg.config_path/_rdmi.name)
+
+# %% ../nbs/api/14_quarto.ipynb 25
 @call_parse
 def nbdev_readme(
     path:str=None, # Path to notebooks
     chk_time:bool=False): # Only build if out of date
     cfg = get_config()
-    cfg_path = cfg.config_path
     path = Path(path) if path else cfg.nbs_path
-    idx_path = path/cfg.readme_nb
-    if not idx_path.exists(): return print(f"Could not find {idx_path}")
-    readme_path = cfg_path/'README.md'
-    if chk_time and readme_path.exists() and readme_path.stat().st_mtime>=idx_path.stat().st_mtime: return
-
-    yml_path = path/'sidebar.yml'
-    moved=False
-    if yml_path.exists():
-        # move out of the way to avoid rendering whole website
-        yml_path.rename(path/'sidebar.yml.bak')
-        moved=True
+    if chk_time and _readme_not_out_of_date(cfg.config_path/'README.md', path/cfg.readme_nb): return
 
-    try:
+    with SidebarYmlRemoved(path): # to avoid rendering whole website
         cache = proc_nbs(path)
-        idx_cache = cache/cfg.readme_nb
-        _sprun(f'cd "{cache}" && quarto render "{idx_cache}" -o README.md -t gfm --no-execute')
-    finally:
-        if moved: (path/'sidebar.yml.bak').rename(yml_path)
-    tmp_doc_path = cache/cfg.doc_path.name
-    readme = tmp_doc_path/'README.md'
-    if readme.exists():
-        _rdmi = tmp_doc_path/(idx_cache.stem + '_files')
-        if readme_path.exists(): readme_path.unlink() # py37 doesn't have `missing_ok`
-        move(readme, cfg_path)
-        if _rdmi.exists(): _copytree(_rdmi, cfg_path/_rdmi.name) # Supporting files for README
+        _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 23
+# %% ../nbs/api/14_quarto.ipynb 29
 @call_parse
 @delegates(_nbglob_docs)
 def nbdev_docs(
@@ -236,7 +247,7 @@ def nbdev_docs(
     shutil.rmtree(cfg.doc_path, ignore_errors=True)
     move(cache/cfg.doc_path.name, cfg.config_path)
 
-# %% ../nbs/api/14_quarto.ipynb 25
+# %% ../nbs/api/14_quarto.ipynb 31
 @call_parse
 def prepare():
     "Export, test, and clean notebooks, and render README if needed"
@@ -247,7 +258,7 @@ def prepare():
     refresh_quarto_yml()
     nbdev_readme.__wrapped__(chk_time=True)
 
-# %% ../nbs/api/14_quarto.ipynb 27
+# %% ../nbs/api/14_quarto.ipynb 33
 @contextmanager
 def fs_watchdog(func, path, recursive:bool=True):
     "File system watchdog dispatching to `func`"
@@ -263,7 +274,7 @@ class _ProcessHandler(FileSystemEventHandler): dispatch=func
         observer.stop()
         observer.join()
 
-# %% ../nbs/api/14_quarto.ipynb 28
+# %% ../nbs/api/14_quarto.ipynb 34
 @call_parse
 @delegates(_nbglob_docs)
 def nbdev_preview(