nb2md[source]

nb2md(fname:Union[str, Path], exp:Exporter)

Convert a notebook in fname to a markdown file.

We can use nb2md to convert a notebook to a markdown file with an Exporter. Below, we use the exporter given to us by nbdoc.mdx.get_mdx_exporter and use that to create a markdown file from a notebook.

_test_fname = Path('test_files/example_input.ipynb')
_test_dest = Path('test_files/example_input.md')
_test_dest.unlink(missing_ok=True)
assert not _test_dest.exists() # make sure the markdown file doesn't exist

nb2md(fname=_test_fname, exp = get_mdx_exporter()) # create the markdown file
assert _test_dest.exists() # make sure the markdown file does exist
assert len(_test_dest.readlines()) > 10

converting: test_files/example_input.ipynb

!cat {_test_dest}

---
title: my hello page title
description: my hello page description
hide_table_of_contents: true
---


<!--- WARNING: THIS FILE WAS AUTOGENERATED! DO NOT EDIT! Instead, edit the notebook w/the location & name as this file.-->

## This is a test notebook

This is a shell command:

<CodeSection lang="bash">

<CodeInputBlock>


```bash
echo hello
```

</CodeInputBlock>
<CodeOutputBlock>

    hello


</CodeOutputBlock>

</CodeSection>

We are writing a python script to disk:

<CodeSection lang="py title="myflow.py"">

<CodeInputBlock>


```py title="myflow.py"
from metaflow import FlowSpec, step

class MyFlow(FlowSpec):
    
    @step
    def start(self):
        print('this is the start')
        self.next(self.end)
    
    @step
    def end(self):
        print('this is the end')

if __name__ == '__main__':
    MyFlow()
```

</CodeInputBlock>

</CodeSection>

Another shell command where we run a flow:

<CodeSection lang="bash">

<CodeInputBlock>


```bash
python myflow.py run
```

</CodeInputBlock>
<CodeOutputBlock>

     [1644963069213536/start/1 (pid 46840)] Task is starting.
     [1644963069213536/start/1 (pid 46840)] this is the start
     [1644963069213536/start/1 (pid 46840)] Task finished successfully.
    ...

</CodeOutputBlock>

</CodeSection>

This is a normal python cell:

<CodeSection lang="python">

<CodeInputBlock>


```python
a = 2
a
```

</CodeInputBlock>
<CodeOutputBlock>




    2



</CodeOutputBlock>

</CodeSection>

The next cell has a cell tag of `remove_input`, so you should only see the output of the cell:

<CodeSection lang="python">

<CodeOutputBlock>

    hello, you should not see the print statement that produced me


</CodeOutputBlock>

</CodeSection>

parallel_nb2md[source]

parallel_nb2md(basedir:Union[Path, str], exp:Exporter, recursive=True, force_all=False, n_workers=None, pause=0)

Convert all notebooks in dir to markdown files.

You can use parallel_nb2md to recursively convert a directory of notebooks to markdown files.

_test_nbs =  nbglob('test_files/')

parallel_nb2md('test_files/', exp=get_mdx_exporter(), recursive=True)

converting: test_files/run_flow_showstep.ipynb
converting: test_files/hello_world.ipynb
converting: test_files/run_flow.ipynb
converting: test_files/example_input.ipynb
converting: test_files/non_executed.ipynbconverting: test_files/writefile.ipynb

converting: test_files/visibility.ipynb
converting: test_files/doc.ipynb
converting: test_files/exec.ipynb
converting: test_files/frontmatter.ipynb

for f in _test_nbs:
    assert f.with_suffix('.md').exists(), f'{str(f)} does not exist.'

The modified times of notebooks are introspected such notebooks that haven't changed after markdown files have been created will not be converted:

parallel_nb2md('test_files/', exp=get_mdx_exporter(), recursive=True)

No notebooks were modified.

However, you can set force_all = True to force notebooks to convert:

parallel_nb2md('test_files/', exp=get_mdx_exporter(), recursive=True, force_all=True)

converting: test_files/run_flow_showstep.ipynbconverting: test_files/hello_world.ipynb

converting: test_files/run_flow.ipynb
converting: test_files/example_input.ipynb
converting: test_files/writefile.ipynb
converting: test_files/non_executed.ipynb
converting: test_files/visibility.ipynb
converting: test_files/doc.ipynb
converting: test_files/frontmatter.ipynb
converting: test_files/exec.ipynb

nbdoc_build[source]

nbdoc_build(srcdir:str=None, force_all:bool_arg=False, n_workers:int=None, pause:float=0.5)

Build the documentation by converting notebooks in srcdir to markdown

	Type	Default	Details
srcdir	str	None	A directory of notebooks to convert to docs recursively, can also be a filename.
force_all	bool_arg	False	Rebuild even notebooks that havent changed
n_workers	int	None	Number of workers to use
pause	float	0.5	Pause time (in secs) between notebooks to avoid race conditions