fixes #652

Author: jph00

nbdev/doclinks.py

@@ -10,9 +10,7 @@
 from .imports import *
 
 from fastcore.script import *
-from fastcore.imports import *
-from fastcore.basics import *
-from fastcore.imports import *
+from fastcore.utils import *
 from fastcore.meta import delegates
 
 import ast,contextlib
@@ -58,7 +56,6 @@ def _binop_leafs(bo, o):
     else: right = [f'{unparse(bo.right).strip()}.{o.name}']
     return concat(left + right)
 
-# %% ../nbs/04b_doclinks.ipynb 16
 def _all_or_exports(fn):
     code = Path(fn).read_text()
     trees = L(ast.parse(code).body)
@@ -69,10 +66,7 @@ def _get_patch(o):
     if not isinstance(o, (ast.FunctionDef,ast.AsyncFunctionDef)): return
     return first([d for d in o.decorator_list if decor_id(d).startswith('patch')])
 
-def _id_or_attr(a):
-    if hasattr(a, 'id'): return a.id
-    return a.attr
-
+# %% ../nbs/04b_doclinks.ipynb 16
 def get_patch_name(o):
     d = _get_patch(o)
     if not d: return
@@ -98,20 +92,20 @@ def update_syms(self:DocLinks):
     exp = exp.map(f"{self.mod_name}.{{}}")
     self.d['syms'][self.mod_name] = exp.map_dict(partial(self.doc_func, self.mod_name))
 
-# %% ../nbs/04b_doclinks.ipynb 23
+# %% ../nbs/04b_doclinks.ipynb 24
 @patch
 def build_index(self:DocLinks):
     self.update_syms()
     self.d['settings'] = dict(**get_config().d)
     self.write_nbdev_idx()
 
-# %% ../nbs/04b_doclinks.ipynb 25
+# %% ../nbs/04b_doclinks.ipynb 26
 def _doc_link(url, mod, sym=None):
     res = urljoin(url, remove_prefix(mod, get_config()['lib_name']+".")) + '.html'
     if sym: res += "#" + remove_prefix(sym, mod+".").lower()
     return res
 
-# %% ../nbs/04b_doclinks.ipynb 26
+# %% ../nbs/04b_doclinks.ipynb 27
 def build_modidx():
     "Create _modidx.py"
     dest = config_key('lib_path')
@@ -125,7 +119,7 @@ def build_modidx():
     for file in dest.glob("**/*.py"):
         if file.name[0]!='_': DocLinks(file, doc_func, _fn).build_index()
 
-# %% ../nbs/04b_doclinks.ipynb 27
+# %% ../nbs/04b_doclinks.ipynb 28
 @delegates(globtastic, but=['file_glob', 'skip_folder_re'])
 def nbglob(path=None, skip_folder_re = '^[_.]', file_glob='*.ipynb', recursive=True, key='nbs_path',
            as_path=False, **kwargs):
@@ -135,7 +129,7 @@ def nbglob(path=None, skip_folder_re = '^[_.]', file_glob='*.ipynb', recursive=T
     res = globtastic(path, file_glob=file_glob, skip_folder_re=skip_folder_re, **kwargs)
     return res.map(Path) if as_path else res
 
-# %% ../nbs/04b_doclinks.ipynb 28
+# %% ../nbs/04b_doclinks.ipynb 29
 @call_parse
 def nbdev_export(
     path:str=None, # Path or filename
@@ -154,14 +148,14 @@ def nbdev_export(
     add_init(get_config().path('lib_path'))
     build_modidx()
 
-# %% ../nbs/04b_doclinks.ipynb 30
+# %% ../nbs/04b_doclinks.ipynb 31
 def _settings_libs():
     try: # settings.ini doesn't exist yet until you call nbdev_new
         cfg = get_config()
         return cfg.get('strip_libs', cfg.get('lib_path')).split()
     except FileNotFoundError: return 'nbdev'
 
-# %% ../nbs/04b_doclinks.ipynb 31
+# %% ../nbs/04b_doclinks.ipynb 32
 class NbdevLookup:
     "Mapping from symbol names to URLs with docs"
     def __init__(self, strip_libs=None, incl_libs=None, skip_mods=None):
@@ -184,7 +178,7 @@ def __init__(self, strip_libs=None, incl_libs=None, skip_mods=None):
 
     def __getitem__(self, s): return self.syms.get(s, None)
 
-# %% ../nbs/04b_doclinks.ipynb 39
+# %% ../nbs/04b_doclinks.ipynb 40
 @patch
 def _link_sym(self:NbdevLookup, m):
     l = m.group(1)

nbdev/export.py

@@ -30,7 +30,8 @@ def _export_(self, nbp, cell, exp_to=None):
 def black_format(cell, # A cell node 
                  force=False): # Turn black formatting on regardless of settings.ini
     "Format code with `black`"
-    cfg = get_config()
+    try: cfg = get_config()
+    except FileNotFoundError: return
     if (str(cfg.get('black_formatting')).lower() != 'true' and not force) or cell.cell_type != 'code': return
     try: import black
     except: raise ImportError("You must install black: `pip install black` if you wish to use black formatting with nbdev")
@@ -53,9 +54,9 @@ def create_modules(path, dest, procs=None, debug=False, mod_maker=ModuleMaker):
                 "See https://nbdev.fast.ai/getting_started.html for more information.")
             return
         mm = mod_maker(dest=dest, name=name, nb_path=path, is_new=mod=='#')
-        mm.make(cells, all_cells)
+        mm.make(cells, all_cells, lib_path=dest)
 
-# %% ../nbs/04a_export.ipynb 16
+# %% ../nbs/04a_export.ipynb 17
 def nb_export(nbname, lib_path=None):
     if lib_path is None: lib_path = get_config().path('lib_path')
     create_modules(nbname, lib_path, procs=[black_format])

nbdev/maker.py

@@ -178,12 +178,12 @@ def _import2relative(cells, lib_name=None):
 
 # %% ../nbs/02_maker.ipynb 32
 @patch
-def make(self:ModuleMaker, cells, all_cells=None, lib_name=None):
+def make(self:ModuleMaker, cells, all_cells=None, lib_path=None):
     "Write module containing `cells` with `__all__` generated from `all_cells`"
     if all_cells is None: all_cells = cells
     if self.parse: 
-        libnm = get_config().path('lib_path')
-        mod_dir = os.path.relpath(self.fname.parent, libnm.parent)
+        if not lib_path: lib_path = get_config().path('lib_path')
+        mod_dir = os.path.relpath(self.fname.parent, Path(lib_path).parent)
         _import2relative(all_cells, mod_dir)
     if not self.is_new: return self._make_exists(cells, all_cells)
 

nbdev/read.py

@@ -48,6 +48,8 @@ def nbdev_create_config(
     doc_path:str='_docs', # Folder name containing docs
     tst_flags:str='', # Test flags
     version:str='0.0.1', # Version number
+    doc_host:str='example.org',  # Hostname for docs
+    doc_base_url:str='/',  # Base URL for docs
     keywords='python', # Keywords for PyPI
     license='apache2', # License for PyPI
     copyright='', # Copyright for PyPI, defaults to author from current year

nbs/01_read.ipynb

@@ -114,6 +114,8 @@
     "    doc_path:str='_docs', # Folder name containing docs\n",
     "    tst_flags:str='', # Test flags\n",
     "    version:str='0.0.1', # Version number\n",
+    "    doc_host:str='example.org',  # Hostname for docs\n",
+    "    doc_base_url:str='/',  # Base URL for docs\n",
     "    keywords='python', # Keywords for PyPI\n",
     "    license='apache2', # License for PyPI\n",
     "    copyright='', # Copyright for PyPI, defaults to author from current year\n",

nbs/02_maker.ipynb

@@ -464,12 +464,12 @@
    "source": [
     "#|export\n",
     "@patch\n",
-    "def make(self:ModuleMaker, cells, all_cells=None, lib_name=None):\n",
+    "def make(self:ModuleMaker, cells, all_cells=None, lib_path=None):\n",
     "    \"Write module containing `cells` with `__all__` generated from `all_cells`\"\n",
     "    if all_cells is None: all_cells = cells\n",
     "    if self.parse: \n",
-    "        libnm = get_config().path('lib_path')\n",
-    "        mod_dir = os.path.relpath(self.fname.parent, libnm.parent)\n",
+    "        if not lib_path: lib_path = get_config().path('lib_path')\n",
+    "        mod_dir = os.path.relpath(self.fname.parent, Path(lib_path).parent)\n",
     "        _import2relative(all_cells, mod_dir)\n",
     "    if not self.is_new: return self._make_exists(cells, all_cells)\n",
     "\n",

nbs/04a_export.ipynb

@@ -104,7 +104,8 @@
     "def black_format(cell, # A cell node \n",
     "                 force=False): # Turn black formatting on regardless of settings.ini\n",
     "    \"Format code with `black`\"\n",
-    "    cfg = get_config()\n",
+    "    try: cfg = get_config()\n",
+    "    except FileNotFoundError: return\n",
     "    if (str(cfg.get('black_formatting')).lower() != 'true' and not force) or cell.cell_type != 'code': return\n",
     "    try: import black\n",
     "    except: raise ImportError(\"You must install black: `pip install black` if you wish to use black formatting with nbdev\")\n",
@@ -145,7 +146,7 @@
     "                \"See https://nbdev.fast.ai/getting_started.html for more information.\")\n",
     "            return\n",
     "        mm = mod_maker(dest=dest, name=name, nb_path=path, is_new=mod=='#')\n",
-    "        mm.make(cells, all_cells)"
+    "        mm.make(cells, all_cells, lib_path=dest)"
    ]
   },
   {

nbs/04b_doclinks.ipynb

@@ -30,9 +30,7 @@
     "from nbdev.imports import *\n",
     "\n",
     "from fastcore.script import *\n",
-    "from fastcore.imports import *\n",
-    "from fastcore.basics import *\n",
-    "from fastcore.imports import *\n",
+    "from fastcore.utils import *\n",
     "from fastcore.meta import delegates\n",
     "\n",
     "import ast,contextlib\n",
@@ -209,7 +207,17 @@
     "    else: left = [f'{unparse(bo.left).strip()}.{o.name}']\n",
     "    if isinstance(bo.right, ast.BinOp): right = _binop_leafs(bo.right, o)\n",
     "    else: right = [f'{unparse(bo.right).strip()}.{o.name}']\n",
-    "    return concat(left + right)"
+    "    return concat(left + right)\n",
+    "\n",
+    "def _all_or_exports(fn):\n",
+    "    code = Path(fn).read_text()\n",
+    "    trees = L(ast.parse(code).body)\n",
+    "    res = read_var(code, '__all__')\n",
+    "    return L(retr_exports(trees) if res is None else res),trees\n",
+    "\n",
+    "def _get_patch(o):\n",
+    "    if not isinstance(o, (ast.FunctionDef,ast.AsyncFunctionDef)): return\n",
+    "    return first([d for d in o.decorator_list if decor_id(d).startswith('patch')])"
    ]
   },
   {
@@ -219,20 +227,6 @@
    "outputs": [],
    "source": [
     "#|export\n",
-    "def _all_or_exports(fn):\n",
-    "    code = Path(fn).read_text()\n",
-    "    trees = L(ast.parse(code).body)\n",
-    "    res = read_var(code, '__all__')\n",
-    "    return L(retr_exports(trees) if res is None else res),trees\n",
-    "\n",
-    "def _get_patch(o):\n",
-    "    if not isinstance(o, (ast.FunctionDef,ast.AsyncFunctionDef)): return\n",
-    "    return first([d for d in o.decorator_list if decor_id(d).startswith('patch')])\n",
-    "\n",
-    "def _id_or_attr(a):\n",
-    "    if hasattr(a, 'id'): return a.id\n",
-    "    return a.attr\n",
-    "\n",
     "def get_patch_name(o):\n",
     "    d = _get_patch(o)\n",
     "    if not d: return\n",
@@ -303,6 +297,13 @@
     "    self.d['syms'][self.mod_name] = exp.map_dict(partial(self.doc_func, self.mod_name))"
    ]
   },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "We have a test notebook we can export to create a test python module:"
+   ]
+  },
   {
    "cell_type": "code",
    "execution_count": null,

nbs/08_showdoc.ipynb

@@ -227,7 +227,7 @@
        "| **Returns** | **int** |  |  |"
       ],
       "text/plain": [
-       "<__main__.DocmentTbl at 0x7fc8d5d35e20>"
+       "<__main__.DocmentTbl at 0x120766a90>"
       ]
      },
      "execution_count": null,
@@ -289,7 +289,7 @@
        "| c | param c |"
       ],
       "text/plain": [
-       "<__main__.DocmentTbl at 0x7fc8d5d355b0>"
+       "<__main__.DocmentTbl at 0x120766850>"
       ]
      },
      "execution_count": null,
@@ -371,7 +371,7 @@
        "| c | str | None |  |"
       ],
       "text/plain": [
-       "<__main__.DocmentTbl at 0x7fc8d5d35820>"
+       "<__main__.DocmentTbl at 0x1207303d0>"
       ]
      },
      "execution_count": null,
@@ -406,7 +406,7 @@
        "| d | bool | True | description of param d |"
       ],
       "text/plain": [
-       "<__main__.DocmentTbl at 0x7fc8d5d35070>"
+       "<__main__.DocmentTbl at 0x120730f10>"
       ]
      },
      "execution_count": null,
@@ -558,50 +558,6 @@
     "You can use `show_doc` to document apis of functions, classes or methods:"
    ]
   },
-  {
-   "cell_type": "code",
-   "execution_count": null,
-   "id": "53a1bc00",
-   "metadata": {},
-   "outputs": [
-    {
-     "data": {
-      "text/markdown": [
-       "---\n",
-       "\n",
-       "#### f\n",
-       "\n",
-       ">      f (x:int=1)\n",
-       "\n",
-       "func docstring"
-      ],
-      "text/plain": [
-       "<__main__.BasicMarkdownRenderer at 0x7fc8d5c50220>"
-      ]
-     },
-     "execution_count": null,
-     "metadata": {},
-     "output_type": "execute_result"
-    }
-   ],
-   "source": [
-    "def f(x:int=1):\n",
-    "    \"func docstring\"\n",
-    "    ...\n",
-    "\n",
-    "show_doc(f)"
-   ]
-  },
-  {
-   "cell_type": "markdown",
-   "id": "66a8dfcd-dc2b-41ce-9d35-5c35e040f25d",
-   "metadata": {},
-   "source": [
-    ":::{.callout-warning}\n",
-    "If you are using a version of python that is older than 3.10, type hints might be rendered as strings when running `show_doc`.  We recommend upgrading to python 3.10 locally if possible so you can preview docs without this artifact.  We have set the version of python to be 3.10 `.github/workflows/deploy.yaml` for this reason as well.\n",
-    ":::"
-   ]
-  },
   {
    "cell_type": "code",
    "execution_count": null,