build_index[source]

build_index(path=None, update_existing=False)

Build an index of names generated with ShowDoc to document paths.

build_index will build an index to names generated with ShowDoc to document paths that we can later use to construct links for documentation.

Consider the follwing two markdown files, test_docs.md and front_matter_with_test_docs.md:

_p1 = Path('test_files/_md_files/test_docs.md')
print(_p1.read_text())

<DocSection type="function" name="function_with_types_in_docstring" module="test_lib.example" show_import="False" heading_level="3">
<SigArgSection>
<SigArg name="param1" /><SigArg name="param2" />
</SigArgSection>
<Description summary="Example function with types documented in the docstring." extended_summary="`PEP 484`_ type annotations are supported. If attribute, parameter, and\nreturn types are annotated according to `PEP 484`_, they do not need to be\nincluded in the docstring:" />
<ParamSection name="Parameters">
	<Parameter name="param1" type="int" desc="The first parameter. something something\nsecond line. foo" />
	<Parameter name="param2" type="str" desc="The second parameter." />
</ParamSection>
<ParamSection name="Returns">
	<Parameter type="bool" desc="True if successful, False otherwise." />
</ParamSection>
</DocSection>

_p2 = Path('test_files/_md_files/front_matter_test_docs.md')
print(_p2.read_text())

---
key2: value2
slug: custom/pathfor/site
key: value
---
<DocSection type="function" name="function_with_pep484_type_annotations" module="test_lib.example" show_import="False" heading_level="3">
<SigArgSection>
<SigArg name="param1" type="int" /><SigArg name="param2" type="str" />
</SigArgSection>
<Description summary="Example function with PEP 484 type annotations." extended_summary="The return type must be duplicated in the docstring to comply\nwith the NumPy docstring style." />
<ParamSection name="Parameters">
	<Parameter name="param1" desc="The first parameter." />
	<Parameter name="param2" desc="The second parameter." />
</ParamSection>
<ParamSection name="Returns">
	<Parameter type="bool" desc="True if successful, False otherwise." />
</ParamSection>
</DocSection>

Notice that for front_matter_test_docs.md, the front matter has a slug, which is used for the path rather than the directory in which the document resides.

Here is how the index looks:

build_index('test_files/')

{'function_with_pep484_type_annotations': 'https://outerbounds.github.io/nbdoc/custom/pathfor/site#function_with_pep484_type_annotations',
 '@batch': 'https://outerbounds.github.io/nbdoc/_md_files/decorators#@batch',
 '@card': 'https://outerbounds.github.io/nbdoc/_md_files/decorators#@card',
 '@catch': 'https://outerbounds.github.io/nbdoc/_md_files/decorators#@catch',
 '@conda': 'https://outerbounds.github.io/nbdoc/_md_files/decorators#@conda',
 '@kubernetes': 'https://outerbounds.github.io/nbdoc/_md_files/decorators#@kubernetes',
 '@parallel': 'https://outerbounds.github.io/nbdoc/_md_files/decorators#@parallel',
 '@project': 'https://outerbounds.github.io/nbdoc/_md_files/decorators#@project',
 '@resources': 'https://outerbounds.github.io/nbdoc/_md_files/decorators#@resources',
 '@step': 'https://outerbounds.github.io/nbdoc/_md_files/decorators#@step',
 'function_with_types_in_docstring': 'https://outerbounds.github.io/nbdoc/_md_files/test_docs#function_with_types_in_docstring'}

get_idx[source]

get_idx(url)

class NbdevLookup[source]

NbdevLookup(local=True, md_path=None, update_existing=False)

Mapping from symbol names to URLs with docs

NbdevLookup can help you linkify markdown.

Here is an example of a file before linkifying it:

print(_backticks_file.read_text())

Hey I am going to see what happens when we have things like `@conda` and `@batch`, but you will not convert conda to a link because it isn't in back ticks.

If something isn't in the index like `@lorem`, nothing will happen.

```py
In code fences you will not convert links `@conda`
```

# Some other md

this is another test: `function_with_types_in_docstring`

And after linkifying it:

nl = NbdevLookup(md_path='test_files/_md_files/')
nl.update_markdown()

Updating: test_files/_md_files/front_matter2.md
Updating: test_files/_md_files/backticks.md
Updating: test_files/_md_files/false_fm2.md
Updating: test_files/_md_files/front_matter_test_docs.md
Updating: test_files/_md_files/front_matter3.md
Updating: test_files/_md_files/decorators.md
Updating: test_files/_md_files/false_fm.md
Updating: test_files/_md_files/test_docs.md

print(_backticks_file.read_text())

Hey I am going to see what happens when we have things like [@conda](https://outerbounds.github.io/nbdoc/decorators#@conda) and [@batch](https://outerbounds.github.io/nbdoc/decorators#@batch), but you will not convert conda to a link because it isn't in back ticks.

If something isn't in the index like `@lorem`, nothing will happen.

```py
In code fences you will not convert links `@conda`
```

# Some other md

this is another test: [function_with_types_in_docstring](https://outerbounds.github.io/nbdoc/test_docs#function_with_types_in_docstring)

nbdoc_linkify[source]

nbdoc_linkify(local:"Whether or not to build an index based on local documents", keep_existing:"Whether or not to keep existing index", md_path:"Root path to search recursively containing markdown files to linkify"=None)

Convert names in backticks in markdown files that have been documented with nbdoc.showdoc.ShowDoc to appropriate links.