fixes #911

Author: jph00

.gitignore

@@ -1,3 +1,4 @@
+nbdev/_modidx.py
 nbdev/tutorial.py
 tests/settings.ini
 idx/

nbdev/_modidx.py

@@ -137,7 +137,7 @@ def _settings_libs():
 
 # %% ../nbs/04b_doclinks.ipynb 19
 class NbdevLookup:
-    "Mapping from symbol names to URLs with docs"
+    "Mapping from symbol names to docs and source URLs"
     def __init__(self, strip_libs=None, incl_libs=None, skip_mods=None):
         if strip_libs is None: strip_libs = _settings_libs()
         skip_mods = setify(skip_mods)
@@ -156,15 +156,16 @@ def __init__(self, strip_libs=None, incl_libs=None, skip_mods=None):
                 py_syms = merge(stripped, py_syms)
         self.syms = py_syms
 
-    def __getitem__(self, s):
-        res = self.syms.get(s, None)
+    def __getitem__(self, s): return self.syms.get(s, None)
+    def doc(self, s):
+        res = self[s]
         return res[0] if isinstance(res, tuple) else res
 
 # %% ../nbs/04b_doclinks.ipynb 27
 @patch
 def _link_sym(self:NbdevLookup, m):
     l = m.group(1)
-    s = self[l]
+    s = self.doc(l)
     if s is None: return m.group(0)
     l = l.replace('\\', r'\\')
     return rf"[`{l}`]({s})"

nbdev/doclinks.py

@@ -1,7 +1,7 @@
 # AUTOGENERATED! DO NOT EDIT! File to edit: ../nbs/06_merge.ipynb.
 
 # %% auto 0
-__all__ = ['conf_re', 'nbdev_fix', 'unpatch', 'nbdev_merge']
+__all__ = ['conf_re', 'unpatch', 'nbdev_fix', 'nbdev_merge']
 
 # %% ../nbs/06_merge.ipynb 2
 from .imports import *
@@ -54,7 +54,8 @@ def _merge_cells(a, b, brancha, branchb, theirs):
     return res,conflict
 
 # %% ../nbs/06_merge.ipynb 23
-def _nbdev_fix(nbname:str, # Notebook filename to fix
+@call_parse
+def nbdev_fix(nbname:str, # Notebook filename to fix
                outname:str=None, # Filename of output notebook (defaults to `nbname`)
                nobackup:bool_arg=True, # Do not backup `nbname` to `nbname`.bak if `outname` not provided
                theirs:bool=False, # Use their outputs and metadata instead of ours
@@ -74,15 +75,12 @@ def _nbdev_fix(nbname:str, # Notebook filename to fix
         else: print("Successfully merged conflicts!")
     return conflict
 
-# %% ../nbs/06_merge.ipynb 24
-nbdev_fix = call_parse(_nbdev_fix)
-
-# %% ../nbs/06_merge.ipynb 28
+# %% ../nbs/06_merge.ipynb 27
 def _git_branch_merge():
     try: return only(v for k,v in os.environ.items() if k.startswith('GITHEAD'))
     except ValueError: return
 
-# %% ../nbs/06_merge.ipynb 29
+# %% ../nbs/06_merge.ipynb 28
 def _git_rebase_head():
     for d in ('apply','merge'):
         d = Path(f'.git/rebase-{d}')
@@ -91,17 +89,17 @@ def _git_rebase_head():
             msg = run(f'git show-branch --no-name {cmt}')
             return f'{cmt[:7]} ({msg})'
 
-# %% ../nbs/06_merge.ipynb 30
+# %% ../nbs/06_merge.ipynb 29
 def _git_merge_file(base, ours, theirs):
     "`git merge-file` with expected labels depending on if a `merge` or `rebase` is in-progress"
     l_theirs = _git_rebase_head() or _git_branch_merge() or 'THEIRS'
     cmd = f"git merge-file -L HEAD -L BASE -L '{l_theirs}' {ours} {base} {theirs}"
     return subprocess.run(cmd, shell=True, capture_output=True, text=True)
 
-# %% ../nbs/06_merge.ipynb 31
+# %% ../nbs/06_merge.ipynb 30
 @call_parse
 def nbdev_merge(base:str, ours:str, theirs:str, path:str):
     "Git merge driver for notebooks"
     if not _git_merge_file(base, ours, theirs).returncode: return
     theirs = str2bool(os.environ.get('THEIRS', False))
-    return _nbdev_fix(ours, theirs=theirs)
+    return nbdev_fix.__wrapped__(ours, theirs=theirs)

nbdev/merge.py

@@ -6,6 +6,7 @@
 
 from .config import *
 from .doclinks import *
+from .doclinks import _build_modidx
 
 from fastcore.utils import *
 from fastcore.script import call_parse
@@ -239,6 +240,7 @@ def nbdev_quarto(
     nbdev_sidebar.__wrapped__(path, file_glob=file_glob, **kwargs)
     pys = globtastic(path, file_glob='*.py', **kwargs).filter(_is_qpy)
     for py in pys: _exec_py(py)
+    _build_modidx()
     if preview: os.system(f'cd "{path}" && quarto preview --port {port}')
     else: _sprun(f'cd "{path}" && quarto render')
     if not preview:

nbdev/quarto.py

@@ -327,7 +327,7 @@
    "source": [
     "#|export\n",
     "class NbdevLookup:\n",
-    "    \"Mapping from symbol names to URLs with docs\"\n",
+    "    \"Mapping from symbol names to docs and source URLs\"\n",
     "    def __init__(self, strip_libs=None, incl_libs=None, skip_mods=None):\n",
     "        if strip_libs is None: strip_libs = _settings_libs()\n",
     "        skip_mods = setify(skip_mods)\n",
@@ -346,8 +346,9 @@
     "                py_syms = merge(stripped, py_syms)\n",
     "        self.syms = py_syms\n",
     "\n",
-    "    def __getitem__(self, s):\n",
-    "        res = self.syms.get(s, None)\n",
+    "    def __getitem__(self, s): return self.syms.get(s, None)\n",
+    "    def doc(self, s):\n",
+    "        res = self[s]\n",
     "        return res[0] if isinstance(res, tuple) else res"
    ]
   },
@@ -365,10 +366,10 @@
    "outputs": [],
    "source": [
     "c = NbdevLookup()\n",
-    "assert c['nbdev.doclinks.NbdevLookup'].startswith('http')\n",
-    "assert c['numpy.array'].startswith('http')\n",
-    "assert c['NbdevLookup'].startswith('http')\n",
-    "assert not c['array']"
+    "assert c.doc('nbdev.doclinks.NbdevLookup').startswith('http')\n",
+    "assert c.doc('numpy.array').startswith('http')\n",
+    "assert c.doc('NbdevLookup').startswith('http')\n",
+    "assert not c.doc('array')"
    ]
   },
   {
@@ -385,7 +386,7 @@
    "outputs": [],
    "source": [
     "c = NbdevLookup(strip_libs=['nbdev', 'nbdev_numpy'])\n",
-    "assert c['array'].startswith('http')"
+    "assert c.doc('array').startswith('http')"
    ]
   },
   {
@@ -401,10 +402,7 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "_nbdev_lookup = NbdevLookup()\n",
-    "assert _nbdev_lookup['NbdevLookup'].startswith('http')\n",
-    "assert _nbdev_lookup['numpy.array'].startswith('http')\n",
-    "assert not _nbdev_lookup['array']"
+    "assert NbdevLookup().doc('NbdevLookup').startswith('http')"
    ]
   },
   {
@@ -424,7 +422,7 @@
     "@patch\n",
     "def _link_sym(self:NbdevLookup, m):\n",
     "    l = m.group(1)\n",
-    "    s = self[l]\n",
+    "    s = self.doc(l)\n",
     "    if s is None: return m.group(0)\n",
     "    l = l.replace('\\\\', r'\\\\')\n",
     "    return rf\"[`{l}`]({s})\"\n",

nbs/04b_doclinks.ipynb

@@ -62,7 +62,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "When working with jupyter notebooks (which are json files behind the scenes) and GitHub, it is very common that a merge conflict (that will add new lines in the notebook source file) will break some notebooks you are working on. This module defines the function `fix_conflicts` to fix those notebooks for you, and attempt to automatically merge standard conflicts. The remaining ones will be delimited by markdown cells like this:"
+    "When working with jupyter notebooks (which are json files behind the scenes) and GitHub, it is very common that a merge conflict (that will add new lines in the notebook source file) will break some notebooks you are working on. This module defines the function `nbdev_fix` to fix those notebooks for you, and attempt to automatically merge standard conflicts. The remaining ones will be delimited by markdown cells like this:"
    ]
   },
   {
@@ -273,7 +273,30 @@
      "data": {
       "text/markdown": [
        "```json\n",
-       "{ 'cells': [{'cell_type': 'code', 'execution_count': 6, 'metadata': {}, 'outputs': [{'data': {'text/plain': ['3']}, 'execution_count': 6, 'metadata': {}, 'output_type': 'execute_result'}], 'source': 'z=3\\nz', 'idx_': 0}, {'cell_type': 'code', 'execution_count': 5, 'metadata': {}, 'outputs': [{'data': {'text/plain': ['6']}, 'execution_count': 7, 'metadata': {}, 'output_type': 'execute_result'}], 'source': 'x=3\\ny=3\\nx+y', 'idx_': 1}, {'cell_type': 'code', 'execution_count': None, 'metadata': {}, 'outputs': [], 'source': '', 'idx_': 2}],\n",
+       "{ 'cells': [ { 'cell_type': 'code',\n",
+       "               'execution_count': 6,\n",
+       "               'idx_': 0,\n",
+       "               'metadata': {},\n",
+       "               'outputs': [ { 'data': {'text/plain': ['3']},\n",
+       "                              'execution_count': 6,\n",
+       "                              'metadata': {},\n",
+       "                              'output_type': 'execute_result'}],\n",
+       "               'source': 'z=3\\nz'},\n",
+       "             { 'cell_type': 'code',\n",
+       "               'execution_count': 5,\n",
+       "               'idx_': 1,\n",
+       "               'metadata': {},\n",
+       "               'outputs': [ { 'data': {'text/plain': ['6']},\n",
+       "                              'execution_count': 7,\n",
+       "                              'metadata': {},\n",
+       "                              'output_type': 'execute_result'}],\n",
+       "               'source': 'x=3\\ny=3\\nx+y'},\n",
+       "             { 'cell_type': 'code',\n",
+       "               'execution_count': None,\n",
+       "               'idx_': 2,\n",
+       "               'metadata': {},\n",
+       "               'outputs': [],\n",
+       "               'source': ''}],\n",
        "  'metadata': { 'kernelspec': { 'display_name': 'Python 3',\n",
        "                                'language': 'python',\n",
        "                                'name': 'python3'}},\n",
@@ -282,7 +305,30 @@
        "```"
       ],
       "text/plain": [
-       "{'cells': (#3) [{'cell_type': 'code', 'execution_count': 6, 'metadata': {}, 'outputs': [{'data': {'text/plain': ['3']}, 'execution_count': 6, 'metadata': {}, 'output_type': 'execute_result'}], 'source': 'z=3\\nz', 'idx_': 0},{'cell_type': 'code', 'execution_count': 5, 'metadata': {}, 'outputs': [{'data': {'text/plain': ['6']}, 'execution_count': 7, 'metadata': {}, 'output_type': 'execute_result'}], 'source': 'x=3\\ny=3\\nx+y', 'idx_': 1},{'cell_type': 'code', 'execution_count': None, 'metadata': {}, 'outputs': [], 'source': '', 'idx_': 2}],\n",
+       "{'cells': [{'cell_type': 'code',\n",
+       "   'execution_count': 6,\n",
+       "   'metadata': {},\n",
+       "   'outputs': [{'data': {'text/plain': ['3']},\n",
+       "     'execution_count': 6,\n",
+       "     'metadata': {},\n",
+       "     'output_type': 'execute_result'}],\n",
+       "   'source': 'z=3\\nz',\n",
+       "   'idx_': 0},\n",
+       "  {'cell_type': 'code',\n",
+       "   'execution_count': 5,\n",
+       "   'metadata': {},\n",
+       "   'outputs': [{'data': {'text/plain': ['6']},\n",
+       "     'execution_count': 7,\n",
+       "     'metadata': {},\n",
+       "     'output_type': 'execute_result'}],\n",
+       "   'source': 'x=3\\ny=3\\nx+y',\n",
+       "   'idx_': 1},\n",
+       "  {'cell_type': 'code',\n",
+       "   'execution_count': None,\n",
+       "   'metadata': {},\n",
+       "   'outputs': [],\n",
+       "   'source': '',\n",
+       "   'idx_': 2}],\n",
        " 'metadata': {'kernelspec': {'display_name': 'Python 3',\n",
        "   'language': 'python',\n",
        "   'name': 'python3'}},\n",
@@ -309,7 +355,30 @@
      "data": {
       "text/markdown": [
        "```json\n",
-       "{ 'cells': [{'cell_type': 'code', 'execution_count': 6, 'metadata': {}, 'outputs': [{'data': {'text/plain': ['3']}, 'execution_count': 6, 'metadata': {}, 'output_type': 'execute_result'}], 'source': 'z=2\\nz', 'idx_': 0}, {'cell_type': 'code', 'execution_count': 5, 'metadata': {}, 'outputs': [{'data': {'text/plain': ['6']}, 'execution_count': 5, 'metadata': {}, 'output_type': 'execute_result'}], 'source': 'x=3\\ny=3\\nx+y', 'idx_': 1}, {'cell_type': 'code', 'execution_count': None, 'metadata': {}, 'outputs': [], 'source': '', 'idx_': 2}],\n",
+       "{ 'cells': [ { 'cell_type': 'code',\n",
+       "               'execution_count': 6,\n",
+       "               'idx_': 0,\n",
+       "               'metadata': {},\n",
+       "               'outputs': [ { 'data': {'text/plain': ['3']},\n",
+       "                              'execution_count': 6,\n",
+       "                              'metadata': {},\n",
+       "                              'output_type': 'execute_result'}],\n",
+       "               'source': 'z=2\\nz'},\n",
+       "             { 'cell_type': 'code',\n",
+       "               'execution_count': 5,\n",
+       "               'idx_': 1,\n",
+       "               'metadata': {},\n",
+       "               'outputs': [ { 'data': {'text/plain': ['6']},\n",
+       "                              'execution_count': 5,\n",
+       "                              'metadata': {},\n",
+       "                              'output_type': 'execute_result'}],\n",
+       "               'source': 'x=3\\ny=3\\nx+y'},\n",
+       "             { 'cell_type': 'code',\n",
+       "               'execution_count': None,\n",
+       "               'idx_': 2,\n",
+       "               'metadata': {},\n",
+       "               'outputs': [],\n",
+       "               'source': ''}],\n",
        "  'metadata': { 'kernelspec': { 'display_name': 'Python 3',\n",
        "                                'language': 'python',\n",
        "                                'name': 'python3'}},\n",
@@ -318,7 +387,30 @@
        "```"
       ],
       "text/plain": [
-       "{'cells': (#3) [{'cell_type': 'code', 'execution_count': 6, 'metadata': {}, 'outputs': [{'data': {'text/plain': ['3']}, 'execution_count': 6, 'metadata': {}, 'output_type': 'execute_result'}], 'source': 'z=2\\nz', 'idx_': 0},{'cell_type': 'code', 'execution_count': 5, 'metadata': {}, 'outputs': [{'data': {'text/plain': ['6']}, 'execution_count': 5, 'metadata': {}, 'output_type': 'execute_result'}], 'source': 'x=3\\ny=3\\nx+y', 'idx_': 1},{'cell_type': 'code', 'execution_count': None, 'metadata': {}, 'outputs': [], 'source': '', 'idx_': 2}],\n",
+       "{'cells': [{'cell_type': 'code',\n",
+       "   'execution_count': 6,\n",
+       "   'metadata': {},\n",
+       "   'outputs': [{'data': {'text/plain': ['3']},\n",
+       "     'execution_count': 6,\n",
+       "     'metadata': {},\n",
+       "     'output_type': 'execute_result'}],\n",
+       "   'source': 'z=2\\nz',\n",
+       "   'idx_': 0},\n",
+       "  {'cell_type': 'code',\n",
+       "   'execution_count': 5,\n",
+       "   'metadata': {},\n",
+       "   'outputs': [{'data': {'text/plain': ['6']},\n",
+       "     'execution_count': 5,\n",
+       "     'metadata': {},\n",
+       "     'output_type': 'execute_result'}],\n",
+       "   'source': 'x=3\\ny=3\\nx+y',\n",
+       "   'idx_': 1},\n",
+       "  {'cell_type': 'code',\n",
+       "   'execution_count': None,\n",
+       "   'metadata': {},\n",
+       "   'outputs': [],\n",
+       "   'source': '',\n",
+       "   'idx_': 2}],\n",
        " 'metadata': {'kernelspec': {'display_name': 'Python 3',\n",
        "   'language': 'python',\n",
        "   'name': 'python3'}},\n",
@@ -386,7 +478,8 @@
    "outputs": [],
    "source": [
     "#|export\n",
-    "def _nbdev_fix(nbname:str, # Notebook filename to fix\n",
+    "@call_parse\n",
+    "def nbdev_fix(nbname:str, # Notebook filename to fix\n",
     "               outname:str=None, # Filename of output notebook (defaults to `nbname`)\n",
     "               nobackup:bool_arg=True, # Do not backup `nbname` to `nbname`.bak if `outname` not provided\n",
     "               theirs:bool=False, # Use their outputs and metadata instead of ours\n",
@@ -407,16 +500,6 @@
     "    return conflict"
    ]
   },
-  {
-   "cell_type": "code",
-   "execution_count": null,
-   "metadata": {},
-   "outputs": [],
-   "source": [
-    "#|export\n",
-    "nbdev_fix = call_parse(_nbdev_fix)"
-   ]
-  },
   {
    "cell_type": "markdown",
    "metadata": {},
@@ -507,20 +590,15 @@
     "    \"Git merge driver for notebooks\"\n",
     "    if not _git_merge_file(base, ours, theirs).returncode: return\n",
     "    theirs = str2bool(os.environ.get('THEIRS', False))\n",
-    "    return _nbdev_fix(ours, theirs=theirs)"
-   ]
-  },
-  {
-   "cell_type": "markdown",
-   "metadata": {},
-   "source": [
-    "This implements a [git merge driver](https://git-scm.com/docs/gitattributes#_defining_a_custom_merge_driver) for notebooks that automatically resolves conflicting metadata and outputs, and splits remaining conflicts as separate cells so that the notebook can be viewed and fixed in Jupyter. The easiest way to install it is by running `nbdev_install_hooks`."
+    "    return nbdev_fix.__wrapped__(ours, theirs=theirs)"
    ]
   },
   {
    "cell_type": "markdown",
    "metadata": {},
    "source": [
+    "This implements a [git merge driver](https://git-scm.com/docs/gitattributes#_defining_a_custom_merge_driver) for notebooks that automatically resolves conflicting metadata and outputs, and splits remaining conflicts as separate cells so that the notebook can be viewed and fixed in Jupyter. The easiest way to install it is by running `nbdev_install_hooks`.\n",
+    "\n",
     "This works by first running Git's default merge driver, and then `nbdev_fix` if there are still conflicts. You can set `nbdev_fix`'s `theirs` argument using the `THEIRS` environment variable, for example:\n",
     "\n",
     "    THEIRS=True git merge branch"
@@ -540,8 +618,7 @@
    "outputs": [],
    "source": [
     "#|hide\n",
-    "from nbdev.doclinks import nbdev_export\n",
-    "nbdev_export()"
+    "import nbdev.doclinks; nbdev.nbdev_export()"
    ]
   },
   {

nbs/06_merge.ipynb

@@ -33,6 +33,7 @@
     "\n",
     "from nbdev.config import *\n",
     "from nbdev.doclinks import *\n",
+    "from nbdev.doclinks import _build_modidx\n",
     "\n",
     "from fastcore.utils import *\n",
     "from fastcore.script import call_parse\n",
@@ -435,6 +436,7 @@
     "    nbdev_sidebar.__wrapped__(path, file_glob=file_glob, **kwargs)\n",
     "    pys = globtastic(path, file_glob='*.py', **kwargs).filter(_is_qpy)\n",
     "    for py in pys: _exec_py(py)\n",
+    "    _build_modidx()\n",
     "    if preview: os.system(f'cd \"{path}\" && quarto preview --port {port}')\n",
     "    else: _sprun(f'cd \"{path}\" && quarto render')\n",
     "    if not preview:\n",