feat: add docs URL to exported module docstrings

nbdev/_modidx.py

@@ -52,6 +52,8 @@
                               'nbdev.config.import_obj': ('api/config.html#import_obj', 'nbdev/config.py'),
                               'nbdev.config.is_nbdev': ('api/config.html#is_nbdev', 'nbdev/config.py'),
                               'nbdev.config.nbdev_create_config': ('api/config.html#nbdev_create_config', 'nbdev/config.py'),
+                              'nbdev.config.nbpath2docurl': ('api/config.html#nbpath2docurl', 'nbdev/config.py'),
+                              'nbdev.config.nbpath2html': ('api/config.html#nbpath2html', 'nbdev/config.py'),
                               'nbdev.config.read_version': ('api/config.html#read_version', 'nbdev/config.py'),
                               'nbdev.config.set_version': ('api/config.html#set_version', 'nbdev/config.py'),
                               'nbdev.config.show_src': ('api/config.html#show_src', 'nbdev/config.py'),
@@ -82,7 +84,6 @@
                                 'nbdev.doclinks._get_modidx': ('api/doclinks.html#_get_modidx', 'nbdev/doclinks.py'),
                                 'nbdev.doclinks._iter_py_cells': ('api/doclinks.html#_iter_py_cells', 'nbdev/doclinks.py'),
                                 'nbdev.doclinks._lineno': ('api/doclinks.html#_lineno', 'nbdev/doclinks.py'),
-                                'nbdev.doclinks._nbpath2html': ('api/doclinks.html#_nbpath2html', 'nbdev/doclinks.py'),
                                 'nbdev.doclinks._qual_mod': ('api/doclinks.html#_qual_mod', 'nbdev/doclinks.py'),
                                 'nbdev.doclinks._qual_sym': ('api/doclinks.html#_qual_sym', 'nbdev/doclinks.py'),
                                 'nbdev.doclinks._qual_syms': ('api/doclinks.html#_qual_syms', 'nbdev/doclinks.py'),

nbdev/clean.py

@@ -1,4 +1,6 @@
-"""Strip superfluous metadata from notebooks"""
+"""Strip superfluous metadata from notebooks
+
+Docs: https://nbdev.fast.ai/api/clean.html.md"""
 
 # AUTOGENERATED! DO NOT EDIT! File to edit: ../nbs/api/11_clean.ipynb.
 

nbdev/cli.py

@@ -1,4 +1,6 @@
-"""CLI commands"""
+"""CLI commands
+
+Docs: https://nbdev.fast.ai/api/cli.html.md"""
 
 # AUTOGENERATED! DO NOT EDIT! File to edit: ../nbs/api/13_cli.ipynb.
 

nbdev/config.py

@@ -1,11 +1,13 @@
-"""Configuring nbdev and bootstrapping notebook export"""
+"""Configuring nbdev and bootstrapping notebook export
+
+Docs: https://nbdev.fast.ai/api/config.html.md"""
 
 # AUTOGENERATED! DO NOT EDIT! File to edit: ../nbs/api/01_config.ipynb.
 
 # %% auto #0
 __all__ = ['pyproject_nm', 'pyproject_tmpl', 'nbdev_defaults', 'pyproj_tmpl', 'nbdev_create_config', 'ConfigToml', 'get_config',
-           'is_nbdev', 'create_output', 'show_src', 'read_version', 'set_version', 'bump_version', 'update_version',
-           'update_proj', 'add_init', 'import_obj', 'write_cells']
+           'is_nbdev', 'create_output', 'show_src', 'nbpath2html', 'nbpath2docurl', 'read_version', 'set_version',
+           'bump_version', 'update_version', 'update_proj', 'add_init', 'import_obj', 'write_cells']
 
 # %% ../nbs/api/01_config.ipynb #6fd14ecd
 from datetime import datetime
@@ -16,7 +18,7 @@
 from fastcore.style import *
 from fastcore.xdg import *
 
-import ast,importlib,warnings
+import ast,importlib,re,warnings
 from IPython.display import Markdown
 from fastcore.nbio import read_nb,NbCell
 from urllib.error import HTTPError
@@ -254,6 +256,20 @@ def create_output(txt, mime):
 # %% ../nbs/api/01_config.ipynb #5a4d8e52
 def show_src(src, lang='python'): return Markdown(f'```{lang}\n{src}\n```')
 
+# %% ../nbs/api/01_config.ipynb #14a9c607
+def nbpath2html(p):
+    "Convert notebook path `p` to its html doc path (strips numeric prefix)"
+    p = Path(p)
+    return p.with_name(re.sub(r'^\d+[a-zA-Z0-9]*_', '', p.name.lower())).with_suffix('.html')
+
+# %% ../nbs/api/01_config.ipynb #c830bb2b
+def nbpath2docurl(nb_path):
+    "Hosted docs URL (with `.md` suffix) for notebook `nb_path`, or '' if no `doc_host`"
+    cfg = get_config()
+    if not cfg.doc_host: return ''
+    p = Path(nb_path).resolve().relative_to(cfg.path('nbs_path'))
+    return f"{cfg.doc_host.rstrip('/')}{cfg.doc_baseurl}{nbpath2html(p).as_posix()}.md"
+
 # %% ../nbs/api/01_config.ipynb #163177f2
 pyproj_tmpl = """[build-system]
 requires = ["setuptools>=64.0"]

nbdev/diff.py

@@ -1,4 +1,6 @@
-"""Get ipynb diffs by cell"""
+"""Get ipynb diffs by cell
+
+Docs: https://nbdev.fast.ai/api/diff.html.md"""
 
 # AUTOGENERATED! DO NOT EDIT! File to edit: ../nbs/api/19_diff.ipynb.
 

nbdev/doclinks.py

@@ -1,4 +1,6 @@
-"""Generating a documentation index from a module"""
+"""Generating a documentation index from a module
+
+Docs: https://nbdev.fast.ai/api/doclinks.html.md"""
 
 # AUTOGENERATED! DO NOT EDIT! File to edit: ../nbs/api/05_doclinks.ipynb.
 
@@ -70,9 +72,6 @@ def _iter_py_cells(p):
         if code.endswith('\n'): code=code[:-1]
         yield AttrDict(nb=nb, cell_id=cell_id, code=code, nb_path=nb_path, py_path=p.resolve())
 
-# %% ../nbs/api/05_doclinks.ipynb #d1c22276
-def _nbpath2html(p): return p.with_name(re.sub(r'^\d+[a-zA-Z0-9]*_', '', p.name.lower())).with_suffix('.html')
-
 # %% ../nbs/api/05_doclinks.ipynb #f57b8709
 def _get_modidx(py_path, code_root, nbs_path):
     "Get module symbol index for a Python source file"
@@ -84,7 +83,7 @@ def _get_modidx(py_path, code_root, nbs_path):
     d = {}
     for cell in _iter_py_cells(py_path):
         if 'auto' in cell.nb: continue
-        loc = _nbpath2html(cell.nb_path.relative_to(nbs_path))
+        loc = nbpath2html(cell.nb_path.relative_to(nbs_path))
 
         def _stor(nm):
             for n in L(nm): d[f'{mod_name}.{n}'] = f'{loc.as_posix()}#{n.lower()}',rel_name

nbdev/export.py

@@ -1,4 +1,6 @@
-"""Exporting a notebook to a library"""
+"""Exporting a notebook to a library
+
+Docs: https://nbdev.fast.ai/api/export.html.md"""
 
 # AUTOGENERATED! DO NOT EDIT! File to edit: ../nbs/api/04_export.ipynb.
 

nbdev/frontmatter.py

@@ -1,4 +1,6 @@
-"""A YAML and formatted-markdown frontmatter processor"""
+"""A YAML and formatted-markdown frontmatter processor
+
+Docs: https://nbdev.fast.ai/api/frontmatter.html.md"""
 
 # AUTOGENERATED! DO NOT EDIT! File to edit: ../nbs/api/09_frontmatter.ipynb.
 
@@ -8,7 +10,7 @@
 # %% ../nbs/api/09_frontmatter.ipynb #2398f5ef-06d3-4890-8a54-7cf4f81f3894
 from .imports import *
 from .process import *
-from .doclinks import _nbpath2html
+from .config import nbpath2html
 
 from fastcore.nbio import *
 from fastcore.imports import *
@@ -80,5 +82,5 @@ def end(self):
                                  'from your _quarto.yml file (e.g. `ipynb-filter: [nbdev_filter]`), since they are no '
                                  'longer supported as of nbdev v2.3. See the v2.3 launch post for more information: '
                                  'https://forums.fast.ai/t/upcoming-changes-in-v2-3-edit-now-released/98905.')
-        self.fm.update({'output-file': _nbpath2html(Path(self.nb.path_)).name})
+        self.fm.update({'output-file': nbpath2html(Path(self.nb.path_)).name})
         _insertfm(self.nb, self.fm)

nbdev/maker.py

@@ -1,4 +1,6 @@
-"""Create one or more modules from selected notebook cells"""
+"""Create one or more modules from selected notebook cells
+
+Docs: https://nbdev.fast.ai/api/maker.html.md"""
 
 # AUTOGENERATED! DO NOT EDIT! File to edit: ../nbs/api/02_maker.ipynb.
 
@@ -174,7 +176,7 @@ def _import2relative(cells, lib_path=None):
     for cell in cells: cell.import2relative(lib_path)
 
 # %% ../nbs/api/02_maker.ipynb #5bff9d71
-def _retr_mdoc(cells):
+def _retr_mdoc(cells, nb_path=None):
     "Search for markdown cells used to create module docstring"
     md1 = first(o for o in cells if o.cell_type=='markdown' and o.source.startswith('# '))
     if not md1: return ''
@@ -183,6 +185,8 @@ def _retr_mdoc(cells):
     summ = '\n'.join(l.lstrip('> ').strip() for l in lines)
     docs = L(o.source.rstrip() for o in cells if o.cell_type=='markdown' and 'export' in getattr(o,'directives_',{}))
     mdoc = '\n\n'.join(L(summ)+docs).strip()
+    url = nbpath2docurl(nb_path) if nb_path else ''
+    if url: mdoc = (mdoc + f'\n\nDocs: {url}').strip()
     return f'"""{mdoc}"""\n\n' if mdoc else ''
 
 # %% ../nbs/api/02_maker.ipynb #cdd205d6
@@ -205,7 +209,7 @@ def make(self:ModuleMaker, cells, all_cells=None, lib_path=None):
         tw = TextWrapper(width=120, initial_indent='', subsequent_indent=' '*11, break_long_words=False)
         all_str = '\n'.join(tw.wrap(str(_all)))
     with self.fname.open('w', encoding="utf-8") as f:
-        f.write(_retr_mdoc(cells))
+        f.write(_retr_mdoc(cells, self.nb_path))
         f.write(f"# AUTOGENERATED! DO NOT EDIT! File to edit: {self.dest2nb}.")
         if last_future > 0: write_cells(cells[:last_future], self.hdr, f)
         if self.parse and not self.solo_nb: f.write(f"\n\n# %% auto #0\n__all__ = {all_str}")

nbdev/merge.py

@@ -1,4 +1,6 @@
-"""Fix merge conflicts in jupyter notebooks"""
+"""Fix merge conflicts in jupyter notebooks
+
+Docs: https://nbdev.fast.ai/api/merge.html.md"""
 
 # AUTOGENERATED! DO NOT EDIT! File to edit: ../nbs/api/07_merge.ipynb.
 

nbdev/migrate.py

@@ -1,4 +1,6 @@
-"""Utilities for migrating to nbdev"""
+"""Utilities for migrating to nbdev
+
+Docs: https://nbdev.fast.ai/api/migrate.html.md"""
 
 # AUTOGENERATED! DO NOT EDIT! File to edit: ../nbs/api/16_migrate.ipynb.
 

nbdev/process.py

@@ -1,4 +1,6 @@
-"""A notebook processor"""
+"""A notebook processor
+
+Docs: https://nbdev.fast.ai/api/process.html.md"""
 
 # AUTOGENERATED! DO NOT EDIT! File to edit: ../nbs/api/03_process.ipynb.
 

nbdev/processors.py

@@ -1,4 +1,6 @@
-"""Some processors for NBProcessor"""
+"""Some processors for NBProcessor
+
+Docs: https://nbdev.fast.ai/api/processors.html.md"""
 
 # AUTOGENERATED! DO NOT EDIT! File to edit: ../nbs/api/10_processors.ipynb.
 

nbdev/qmd.py

@@ -1,4 +1,6 @@
-"""Basic qmd generation helpers (experimental)"""
+"""Basic qmd generation helpers (experimental)
+
+Docs: https://nbdev.fast.ai/api/qmd.html.md"""
 
 # AUTOGENERATED! DO NOT EDIT! File to edit: ../nbs/api/15_qmd.ipynb.
 

nbdev/quarto.py

@@ -1,4 +1,6 @@
-"""Install and interact with Quarto from nbdev"""
+"""Install and interact with Quarto from nbdev
+
+Docs: https://nbdev.fast.ai/api/quarto.html.md"""
 
 # AUTOGENERATED! DO NOT EDIT! File to edit: ../nbs/api/14_quarto.ipynb.
 

nbdev/release.py

@@ -1,4 +1,6 @@
-"""Auto-generated tagged releases and release notes from GitHub issues"""
+"""Auto-generated tagged releases and release notes from GitHub issues
+
+Docs: https://nbdev.fast.ai/api/release.html.md"""
 
 # AUTOGENERATED! DO NOT EDIT! File to edit: ../nbs/api/18_release.ipynb.
 

nbdev/serve.py

@@ -1,4 +1,6 @@
-"""A parallel ipynb processor (experimental)"""
+"""A parallel ipynb processor (experimental)
+
+Docs: https://nbdev.fast.ai/api/serve.html.md"""
 
 # AUTOGENERATED! DO NOT EDIT! File to edit: ../nbs/api/17_serve.ipynb.
 

nbdev/showdoc.py

@@ -1,4 +1,6 @@
-"""Display symbol documentation in notebook and website"""
+"""Display symbol documentation in notebook and website
+
+Docs: https://nbdev.fast.ai/api/showdoc.html.md"""
 
 # AUTOGENERATED! DO NOT EDIT! File to edit: ../nbs/api/08_showdoc.ipynb.
 

nbdev/sync.py

@@ -1,4 +1,6 @@
-"""Propagate small changes in the library back to notebooks"""
+"""Propagate small changes in the library back to notebooks
+
+Docs: https://nbdev.fast.ai/api/sync.html.md"""
 
 # AUTOGENERATED! DO NOT EDIT! File to edit: ../nbs/api/06_sync.ipynb.
 

nbdev/test.py

@@ -1,4 +1,6 @@
-"""Run unit tests on notebooks in parallel"""
+"""Run unit tests on notebooks in parallel
+
+Docs: https://nbdev.fast.ai/api/test.html.md"""
 
 # AUTOGENERATED! DO NOT EDIT! File to edit: ../nbs/api/12_test.ipynb.
 

nbs/api/01_config.ipynb

@@ -38,7 +38,7 @@
     "from fastcore.style import *\n",
     "from fastcore.xdg import *\n",
     "\n",
-    "import ast,importlib,warnings\n",
+    "import ast,importlib,re,warnings\n",
     "from IPython.display import Markdown\n",
     "from fastcore.nbio import read_nb,NbCell\n",
     "from urllib.error import HTTPError\n",
@@ -584,7 +584,7 @@
   {
    "cell_type": "code",
    "execution_count": null,
-   "id": "4b2721ec",
+   "id": "0e254082",
    "metadata": {},
    "outputs": [],
    "source": [
@@ -627,6 +627,58 @@
     "show_src(\"print(create_output('text', 'text/plain'))\")"
    ]
   },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "14a9c607",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "#| export\n",
+    "def nbpath2html(p):\n",
+    "    \"Convert notebook path `p` to its html doc path (strips numeric prefix)\"\n",
+    "    p = Path(p)\n",
+    "    return p.with_name(re.sub(r'^\\d+[a-zA-Z0-9]*_', '', p.name.lower())).with_suffix('.html')"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "f55a2568",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "#| hide\n",
+    "test_eq(nbpath2html(Path('foo/bar/012abc_my.notebook.ipynb')), Path('foo/bar/my.notebook.html'))"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "c830bb2b",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "#| export\n",
+    "def nbpath2docurl(nb_path):\n",
+    "    \"Hosted docs URL (with `.md` suffix) for notebook `nb_path`, or '' if no `doc_host`\"\n",
+    "    cfg = get_config()\n",
+    "    if not cfg.doc_host: return ''\n",
+    "    p = Path(nb_path).resolve().relative_to(cfg.path('nbs_path'))\n",
+    "    return f\"{cfg.doc_host.rstrip('/')}{cfg.doc_baseurl}{nbpath2html(p).as_posix()}.md\""
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "43f3b09e",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "#| hide\n",
+    "test_eq(nbpath2docurl(cfg.nbs_path/'api/01_config.ipynb'), 'https://nbdev.fast.ai/api/config.html.md')"
+   ]
+  },
   {
    "cell_type": "markdown",
    "id": "778e2203",
@@ -946,7 +998,16 @@
    ]
   }
  ],
- "metadata": {},
+ "metadata": {
+  "solveit": {
+   "default_code": true,
+   "mode": "learning",
+   "use_fence": false,
+   "use_thinking": false,
+   "use_tools": true,
+   "ver": 2
+  }
+ },
  "nbformat": 4,
  "nbformat_minor": 5
 }

nbs/api/02_maker.ipynb

@@ -490,7 +490,7 @@
    "outputs": [],
    "source": [
     "#| export\n",
-    "def _retr_mdoc(cells):\n",
+    "def _retr_mdoc(cells, nb_path=None):\n",
     "    \"Search for markdown cells used to create module docstring\"\n",
     "    md1 = first(o for o in cells if o.cell_type=='markdown' and o.source.startswith('# '))\n",
     "    if not md1: return ''\n",
@@ -499,6 +499,8 @@
     "    summ = '\\n'.join(l.lstrip('> ').strip() for l in lines)\n",
     "    docs = L(o.source.rstrip() for o in cells if o.cell_type=='markdown' and 'export' in getattr(o,'directives_',{}))\n",
     "    mdoc = '\\n\\n'.join(L(summ)+docs).strip()\n",
+    "    url = nbpath2docurl(nb_path) if nb_path else ''\n",
+    "    if url: mdoc = (mdoc + f'\\n\\nDocs: {url}').strip()\n",
     "    return f'\"\"\"{mdoc}\"\"\"\\n\\n' if mdoc else ''"
    ]
   },
@@ -544,7 +546,7 @@
     "        tw = TextWrapper(width=120, initial_indent='', subsequent_indent=' '*11, break_long_words=False)\n",
     "        all_str = '\\n'.join(tw.wrap(str(_all)))\n",
     "    with self.fname.open('w', encoding=\"utf-8\") as f:\n",
-    "        f.write(_retr_mdoc(cells))\n",
+    "        f.write(_retr_mdoc(cells, self.nb_path))\n",
     "        f.write(f\"# AUTOGENERATED! DO NOT EDIT! File to edit: {self.dest2nb}.\")\n",
     "        if last_future > 0: write_cells(cells[:last_future], self.hdr, f)\n",
     "        if self.parse and not self.solo_nb: f.write(f\"\\n\\n# %% auto #0\\n__all__ = {all_str}\")\n",