Including jupyter notebooks or markdown tutorials

[braniii]

I just saw that pdoc is back and the new docs are looking very nice :)

Problem Description

Documenting the source code is a good start, but often it helps more if a tutorial and/or some theoretical background is given. Therefore, it would be super cool to allow adding either markdown files, or jupyter notebooks to the documentation.

This is related to the issue of pdoc3: pdoc3/pdoc#115

Proposal

I tried at pdoc3 to propose an implementation: pdoc3/pdoc#394. Not having a config file, I guess it would be sufficient to specify a directory where all included files should be included to the TOC by their name.

[mhils]

Hi @braniii! Thanks for the suggestion. I absolutely see where you are coming from, but this goes a bit beyond what I want pdoc to do. It adds a whole bunch of complexity which I don't want to maintain long-term. Here are the solutions I would recommend instead:

1. Use the top-level docstring in __init__.py for the tutorial / background. This is what we do for pdoc itself (https://github.com/mitmproxy/pdoc/blob/main/pdoc/__init__.py -> https://pdoc.dev/docs/pdoc.html). If you dislike authoring everything in the docstring, you can also include external Markdown files there: https://pdoc.dev/docs/pdoc.html#include-markdown-files
2. Use a static-site generator for most of your website and embed pdoc (https://pdoc.dev/docs/pdoc.html#integrate-pdoc-into-other-systems). This is what we do for mitmproxy (https://docs.mitmproxy.org/dev/api/events.html)
3. Use Sphinx or mkdocs/mkdocstrings.

[braniii]

Hi @mhils, thx for your answer and recommendations. I see your point why you do not want to add this complexity.