Splitting the intro page into multiple pages about pdoc HOT 7 CLOSED

Why not just make a submodule examples with little/no public API code, instead containing just prose introduction? You can then link to it with:

`my_project.examples`

from pdoc.

Why not simply split your project into sensible submodules (example)?

from pdoc.

Hi,
The code is already split into separate modules.
I ask for this functionality for the text/tutorial/examples etc.

from pdoc.

I see. How would this work?

pdoc is meant mainly for API docs! Its primary use case is short usage introduction preceding the API reference.

from pdoc.

I get that. However would be nice if different ..include:: files went to different pages.
What do you think?

from pdoc.

Certainly not with .. include:: as this directive has an established, known outcome (verbatim content injection).

It's not that hard to make a hyperlink explicitly:

Find more examples on the [Examples] page.

[Examples]: ./examples.html

That extra page can then be constructed by any convenient means.

If you're counting mostly on prose documentation, perhaps what you're after is more in line with how Sphinx, MkDocs, or even Nikola operate. (Unfortunately, Nikola only supports old pdoc as a plugin.)

from pdoc.

Opposing the idea, I'll close for the time being. Docs hierarchy follows module hierarchy is one of the main selling points of the program. I think the comment above shows the appropriate way to go.

If you care to find a strong counter argument, envision further details, and propose a reasonable implementation, welcome to comment/reopen.

from pdoc.