Include pages (e.g. notebooks)

[Vayel]

It would be nice to be able to include pages to the docs with the same menu as in the index.

Expected Behavior

Actual Behavior

Currently, I export the notebook to HTML with a template that contains the hard-coded TOC:

Additional info

• pdoc version: 0.6.3

[kernc]

Might you export the notebook to Markdown and use .. include:: reStructuredText directive?

[Vayel]

Thanks for the quick answer! I could do that indeed, but it would make the index page super loaded.

[kernc]

How exactly would the proposed feature be used? I admit I don't envision it clearly. What would the "different TOC" be? Would every module's TOC link to the extra pages that that module includes?

[Vayel]

I would show it on the index page only, just below the TOC:

Ideally, we should be able to customize the order in which the additional pages appear. For instance, people probably want their "Get started" to appear on top.

[braniii]

How exactly would the proposed feature be used? I admit I don't envision it clearly. What would the "different TOC" be? Would every module's TOC link to the extra pages that that module includes?

This feature sounds quite helpful to me. The idea is (if I got it right) to be able to include additional subpages, which are not included in any docstring. So far, this can be achieved with .. include:: ... but this is only helpful, as long as the pages are not too long. If you have, e.g., a gallery with dozens of figures it would improve the readability if one could include them separately. These files could be passed with an extra flag when calling pdoc, e.g.
`pdoc --include extra.md extra2.md extra3.md ... /path/to/module

[zijie0]

This would be super useful for machine learning related projects! Any plans on this?

[kernc]

This would be super useful for machine learning related projects!

In another project I use a pipeline with nbconvert to translate IPython notebooks and link them manually.

I agree it would be useful for all kinds of extra examples. Someone needs to step up with a solid proposal/implementation. 😃

Taking path/to/directory would probably be reasonable, with proper handling of supported files therein. Maybe even default to ./docs as that's the place where people might want to keep their .md originals. We can convert them with some wrapper of pdoc.html_helpers.to_html():

pdoc/pdoc/html_helpers.py

Lines 406 to 409 in c2c1320

	def to_html(text: str, *,
	docformat: str = None,
	module: pdoc.Module = None, link: Callable[..., str] = None,
	latex_math: bool = False):

Other types of files that should probably be supported are .html and .ipynb ...?

Configuration for the extra_docs_dir= could go via config.mako, and then be invoked by

pdoc --config 'extra_docs_dir="my_docs"' ...

[francis-chris5]

I stumbled across this while looking for something else and didn't notice an answer while quickly skimming, I know I'm kind of late here, but this pdf is the instructions I gave my students to do that very same thing in a python class where generated documentation was required instead of regular comments. The pictures are for google colab but the steps worked on Jupyter as well. The part that matters here is at the bottom of the pdf
pdoc instructions page.pdf
.