Generate docs for jupyter notebooks?

[csinva]

Wonderful package! Is there any planned support for jupyter notebooks? Would be really nice to have documentation that automatically extracts the markdown pieces of jupyter notebooks, especially for documenting data-science projects.

[kernc]

How would you expect that to work?

Notebooks are not really Python modules, and they have a suite of conversion tools already built around them. E.g. see jupyter nbconvert. Another option would be jupytext --to py and then pdoc on that. :thinking: I use both of those tools successfully in another project.

[csinva]

Thanks for the quick reply! Those are some very good pointers - they likely are sufficient for general use-cases. Feel free to close 😄 .

What I had envisioned was something that would treat a folder of notebooks similar to a module. Very common practice in data-science projects is to have a src module of useful functions and a folder of notebooks which do analysis using the src module (e.g. see the standard cookiecutter-data-science template).

In most data-science projects I have seen, the notebooks folder quickly accumulates a large number of notebooks and it is difficult to tell what each does / how they are related without opening each notebook one-by-one. Thus it would be extremely useful to auto-generate a documentation-outline of all the notebooks in the folder based on their markdown cells! But maybe this is beyond the scope of this project...

Thanks again!

[kernc]

I believe jupytext --to py notebooks, followed by pdoc --template-dir custom-templates notebooks might fit your use case. In ./custom-templates, you create the undocumented text.mako with the following contents:

<% from pdoc.html_helpers import extract_toc %>
${extract_toc(module.docstring)}

(If you don't need only the heading outline, leave out --template-dir altogether.)

For merely a quick outline, even grep -Pn '^(#+\s*.|\s*(class|def)\s+) notebooks might do.