Configure module index

[Fohlen]

Problem Description

Currently when generating via pdoc, the index.html creates a "module" index with no content, other then a search bar.
When using the documentation, all pages also contain a relative link to this module index, making it inevitable to be seen by customers.

Proposal

I would like to be able to configure the logo, and default content. Ideally specify one module and render that modules description. Ofc this has the additional problem of duplicating documentation - so not sure how to approach this best.

[mhils]

When using the documentation, all pages also contain a relative link to this module index, making it inevitable to be seen by customers.

At the moment we do the following:

1. If there is a parent module and that parent module is documented, display a link to "go one level up".
2. If there is no parent module and more than one module is documented, display a link to the index.

If you see other behavior, please report a bug.

I would like to be able to configure the logo, and default content. Ideally specify one module and render that modules description. Ofc this has the additional problem of duplicating documentation - so not sure how to approach this best.

I think you are raising a reasonable point here that the module index often isn't too useful, but prominently displayed. Maybe we can do something like this:

1. If there is only one module being documented, keep current behavior of not displaying a link.
2. If there is a documented parent module, display a "one level up" button.
3. If all other documented modules are children of the current module (in other words: we're looking at the only top-level module), disable the module index (and display no link). Make index.html redirect to modulename.html instead. All child modules can be reached in the "submodule" list in the navigation.
4. If there are multiple top-level modules, display a link to the module index.
5. Optionally add a --module-index/--no-module-index command line switch that can be used to either force a module index for case 3, or disable module index links for case 4.

Does that make sense? I don't know how much value people get out of the module index at the moment, personally speaking I wouldn't miss it too much if navigation still works.

I would like to be able to configure the logo, and default content. Ideally specify one module and render that modules description. Ofc this has the additional problem of duplicating documentation - so not sure how to approach this best.

Regarding the logo parts, you can change the logo by overwriting the logo template block in index.html.jinja2. I agree though that we should respect --logo here as well. PRs welcome! :)

[abubelinha]

I don't know how much value people get out of the module index at the moment, personally speaking I wouldn't miss it too much if navigation still works.

@mhils For my use case (document and indexing a list of standalone scripts for quick navigation) having a left module index is absolutely fundamental.

I would even like it more if it offered some kind of sorting (by module name, file datetime, file size, ...) or even showing some more info (date last modified, as an additional pdoc.render.configure(show_datetime) option).
I was going to create an enhancement issue asking for that, but perhaps it's more appropriate to post it here?
@abubelinha

[mhils]

I would even like it more if it offered some kind of sorting (by module name, file datetime, file size, ...) or even showing some more info (date last modified, as an additional pdoc.render.configure(show_datetime) option). I was going to create an enhancement issue asking for that, but perhaps it's more appropriate to post it here?

I would like to keep pdoc laser-focused on API documentation for small projects. I don't think file size or datetime would useful to documentation consumers in these cases, so that's nothing I'd like to add to pdoc.

[abubelinha]

I understand. I was suggesting it as an option (turned off by default).
Let me explain a bit more, though.

• I think knowing datetime would give users an idea of which modules have been updated and when (so reading documentation again could be necessary). For messy developers like me, it's a quick way to look for old modules which could need to be upgraded or so.
• Sorting index looks useful to me in any case, because default order follows the order of modules passed to pdoc. At some point, users could prefer to click and sort it by module name, or even by update time (those who see usefulness in what I said).
• I absolutely agree in that file size is useless for most people. To be honest, I wasn't convinced when I put it 3rd in the list ... ;)

[mhils]

I was suggesting it as an option (turned off by default).

Every option is costly: It increases maintenance burden and also cognitive burden for users, who are faced with an ever-increasing list of options. Long story short, my responsibility as the maintainer of pdoc is to say no to some suggestions. :)

[abubelinha]

No problem ... I just feel the need to explain because somebody else had raised thumb to my comment.

Probably nothing I will be ever able to do, but just in case: which .py files should I focus on if I ever grow up as a developer to retouch index myself?

[Fohlen]

Hey @mhils I'll be looking into contributing the feature(s) you discussed in your comment in the future, just haven't gotten around to it yet.

[abubelinha]

@mhils Again, this is a new question closely related to the index, but not to this issue.
But I am not sure if you prefer me to create an issue for asking these kind of things.

I have noticed the similar look between pdoc produced documentation (left index with links to each module content in the main frame), and the look of pdoc's web documentation in this page: https://pdoc.dev/docs/pdoc.html (similar left index, but with an additional tree-look).

Two questions come to my mind:

• Was that page somehow produced using pdoc itself? I would like to know how.
• Is there any current option to generate a similar tree-like index with pdoc, so that members of each module (inner functions' names) are shown indented on the left index? (so we can see them and click directly on the function's name)

I ask this because in my pdoc-generated index, there is not such indentation (i.e. the examples I sent you some days ago).
In left index I can only see modules' names, but not their inner functions (which are visible in pdoc's web documentation index: i.e. here do_HEAD(), do_GET(), log_request() ... are visible and clickable from the left index).

[mhils]

The pdoc docs are created using pdoc itself: https://github.com/mitmproxy/pdoc/blob/main/docs/make.py. There is almost no customization.

[mhils]

@Fohlen: I have a prototype over at #337, which implements the plan mentioned above. Feedback welcome! 😃 If nothing unforseen appears I plan on shipping this with pdoc 9.0 soon-ish.

[Fohlen]

Hi @mhils thanks for taking it upon yourself to implement this! I was wrapped up with other things, and documentation didn't take priority currently - sorry! I added some comments to your PR but overall I think it's great and fits the simplistic approach of pdoc.

[mhils]

No worries - thanks for the review! This is in the main branch now and will be part of the next release.

If you for some reason insist on having a module index, one workaround is to add a second non-public module to the specs, e.g.

pdoc [your module] _json

This makes pdoc believe that multiple modules are being documented, even though the _json module is hidden in the UI because it's private.

[Fohlen]

Just updating you on the ticket that we've tried out the changes in production, and can confirm that I (or we) quite like them. Thanks a lot!