doclinks

Creating the module index

The doc index has to be stored in a file. Usually we call it _modidx.py. For testing, we’ll delete any existing file first.

dest_fn = Path('tmp/_modidx.py')
with contextlib.suppress(FileNotFoundError): dest_fn.unlink()

A link to docs is created by a doc_func. We’ll use a dummy one for testing.

def _help(m, s=None): return f"help for {m}; {s}"

We’re now ready to instantiate DocLinks for our test module.

mod_fn = Path('tmp/everything.py')
link = DocLinks(mod_fn, _help, dest_fn)
link.mod_name
'tmp.everything'

DocLinks.write_nbprocess_idx

 DocLinks.write_nbprocess_idx ()

Create nbprocess documentation index file`

Initially the index file will contain empty syms and settings:

tmp_path = Path('tmp')
tmp_path.mkdir(exist_ok=True)
link.write_nbprocess_idx()
assert "Autogenerated" in dest_fn.read_text()

print(Path('tmp/_modidx.py').read_text())
# Autogenerated by nbprocess

d = {'settings': {}, 'syms': {}}

get_patch_name

 get_patch_name (o)
s = """class _T: pass
@patch
def _f(self:_T): pass
@patch_to(_T)
def _g(self): pass"""

res = [get_patch_name(o) for o in ast.parse(s).body]
test_eq([None, '_T._f', '_T._g'], res)

DocLinks.update_syms

 DocLinks.update_syms ()
everything_fn = '../tests/01_everything.ipynb'
nb_export('../tests/00_some.thing.ipynb', 'tmp')
nb_export(everything_fn, 'tmp')
link.update_syms()
link.write_nbprocess_idx()
g = exec_new('import tmp._modidx')
d = g['tmp']._modidx.d
symn = 'tmp.everything.a_y'
mod_name = 'tmp.everything'
test_eq(d['syms'][mod_name][symn], _help(mod_name,symn))
test_eq(set(d['syms'][mod_name].keys()),
        set(L('m_y', 'n_y', 'q_y', 'a_y', 'b_y', 'd_y', 'e_y', 'o_y', 'p_y', 'd_y.di_n', 'd_y.d3i_n', 'd_y.d4i_n'
             ).map('tmp.everything.{}')))

DocLinks.build_index

 DocLinks.build_index ()
link.build_index()
del(sys.modules['tmp._modidx'])
g = exec_new('import tmp._modidx')
d = g['tmp']._modidx.d
test_eq(d['settings']['lib_name'], 'nbprocess')

build_modidx

 build_modidx ()

Create _modidx.py

nbglob

 nbglob (path=None, skip_folder_re='^[_.]', file_glob='*.ipynb',
         recursive=True, key='nbs_path', as_path=False,
         symlinks:'bool'=True, file_re:'str'=None, folder_re:'str'=None,
         skip_file_glob:'str'=None, skip_file_re:'str'=None,
         func:'callable'=<functionjoinat0x7f1f3351ea70>)

Find all files in a directory matching an extension given a config_key.

Type Default Details
path NoneType None path to start searching passed to globtastic
skip_folder_re str 1 Skip folders matching regex, passed to globtastic
file_glob str *.ipynb Only include files matching glob passed to globtastic
recursive bool True search subfolders passed to globtastic
key str nbs_path
as_path bool False
symlinks bool True follow symlinks? passed to globtastic
file_re str None Only include files matching regex passed to globtastic
folder_re str None Only enter folders matching regex passed to globtastic
skip_file_glob str None Skip files matching glob passed to globtastic
skip_file_re str None Skip files matching regex passed to globtastic
func callable join function to apply to each matched file passed to globtastic

nbprocess_export

 nbprocess_export (path:str=None, recursive:bool=None, symlinks:bool=True,
                   file_re:str=None, folder_re:str=None,
                   skip_file_glob:str=None, skip_file_re:str=None)

Export notebooks in path to python modules

Type Default Details
path str None path or filename
recursive bool None search subfolders
symlinks bool True follow symlinks?
file_re str None Only include files matching regex
folder_re str None Only enter folders matching regex
skip_file_glob str None Skip files matching glob
skip_file_re str None Skip files matching regex

NbdevLookup

 NbdevLookup (strip_libs=None, incl_libs=None, skip_mods=None)

Mapping from symbol names to URLs with docs

Symbol names are taken from libraries registered using the ‘nbprocess’ entry point. By default, all libraries with this entry point are searched, but full symbol names (including module prefix) are required.

c = NbdevLookup()
assert c['nbprocess.doclinks.DocLinks'].startswith('http')
assert c['numpy.array'].startswith('http')
assert c['DocLinks'].startswith('http')
assert not c['array']

Pass strip_libs to list libraries which should be available without requiring a module prefix.

c = NbdevLookup(strip_libs=['nbprocess', 'nbdev_numpy'])
assert c['array'].startswith('http')
assert c['DocLinks'].startswith('http')

nbprocess itself includes nbdev_lookup, an instantiated NbdevLookup with strip_libs=nbprocess.

_nbprocess_lookup = NbdevLookup()
assert _nbprocess_lookup['DocLinks'].startswith('http')
assert _nbprocess_lookup['numpy.array'].startswith('http')
assert not _nbprocess_lookup['array']

Backticks

NbdevLookup.linkify

 NbdevLookup.linkify (md)
md = """This is a link to `numpy.array` and to `get_config` but not a link to `foobar`.
And not a link to <code>dict2nb</code>.

    This is not a link to `get_config`

This isn’t a link to get_config either

c = NbdevLookup('nbprocess')
Markdown(c.linkify(md))

This is a link to numpy.array and to get_config but not a link to foobar. And not a link to dict2nb.

This is not a link to [get_config](https://nbprocess.fast.ai/read#get_config)
This isn't a link to [get_config](https://nbprocess.fast.ai/read#get_config) either
Path('../nbprocess/export.py').unlink(missing_ok=True)
nbprocess_export()

g = exec_new('import nbprocess.export')
assert hasattr(g['nbprocess'].export, 'nb_export')
from nbprocess._modidx import d
assert d['syms']['nbprocess.doclinks']['nbprocess.doclinks.DocLinks'].startswith('http')

Footnotes

  1. _.↩︎