Sidecar documentation?

[woodruffw]

First of all, thanks a ton for this tool! It's (by far) my favorite documentation solution for Python.

I realize that one of the things that makes pdoc3 so great is its simplicity (compared to e.g. Sphrinx), but I figured I'd ask: is there any official (or unofficial, but unlikely to break) mechanism for adding "sidecar" documentation?

For example: given a Python module in src/ and some extra (Markdown) docs in docs/, is it possible to render each of the docs in docs/ and place them in their own ToC/ToC subtree?

I understand if this doesn't exist, and this is not a feature request for it: I just figured I'd ask to make sure I wasn't missing anything.

[kernc]

You're asking for something like https://github.com/pdoc3/pdoc/issues/115?

each of the docs in docs/ and place them in their own ToC/ToC subtree?

Say we support and go over docs/*.md files. How would the TCC subtrees organize? And how would this be configurable to match varied tastes. Might be less than trivial as we currently rely solely on [TOC] tag and Markdown-TOC extension for TOC construction: https://github.com/pdoc3/pdoc/blob/bec63077a03b2136e6982825d327073ed76cc20a/pdoc/html_helpers.py#L538-L548

There are still few blueprints on how such a feature would work.

I like the premise "docs hierarchy follows module hierarchy" a lot. Maybe the easiest would be to pick additional (configurable) .md files in traversed package folders and append a single link to each such document, pretending to be a module, to the TOC ...

Someone needs to think it through.

[woodruffw]

You're asking for something like #115?

Yep, something like that!

And yeah, this could get complicated very quickly. As far as my use case goes: I'd like to be able to include markdown documents that don't mirror the module hierarchy directly, but provide contributing guides/HOW-TOs so that users can make their own changes.

For something like that, my ideal setup would be some sort of separate ToC, either above or below the sub-module index, with entries either sorted alphanumerically or maybe with a separate toc.md or similar file that just lists them in the intended order. One of pdoc3's greatest strengths is not needing configuration, though, so I don't want to suggest anything that strays too far from that :slightly_smiling_face:

[kernc]

Well, if you're able to figure out something that works like that and suits ~90% of cases, I'm all up for it. I do find, however, TOCs where some headings lead to anchors further down the page and other headings to completely different pages somewhat odd, if not unacceptably confusing. So they would have to be marked in a distinct way.

Let's then merge the two issues into that one, since it likely has more subscribers to give voice if necessary. Welcome to subscribe.

Duplicate of https://github.com/pdoc3/pdoc/issues/115.