Index of documented modules

[ryangalamb]

Expected Behavior

A way to include the --http mode's "Python module list" index.html as the root index.html of the --html output.

Actual Behavior

By default, there is no index.html at the top level of the HTML output. There doesn't seem to be a way to enable the "Python module list" in the static html output.

Steps to Reproduce

1. pdoc --html [some modules]
2. nothing at ./html/index.html

Additional info

I'm happy to open a PR for this if it seems like a reasonable request. I'm imagining it as a command line flag to run in addition to --html. When present, pdoc would generate an index.html with the "Python module list" the same as the one generated in WebDoc.do_GET() when path is "/"

• pdoc version: pdoc 0.6.3

[kernc]

I think it's safe to just generate the index.html always, why not? Didn't think of that in #55. 👍

Besides the index file, why not list all top-level, disjunct packages/modules specified on a single command line also in the sidebar below the members list? Pass the modules as modules= and close #95. 🤔

[ryangalamb]

@kernc

I think it's safe to just generate the index.html always, why not?

I'd be hesitant to turn this feature on by default. For my own use case, my docs automation would break if we made this the default. I'm sure others would experience similar problems.

Also, if we make this feature opt-in, we can do nice things like enabling the module breadcrumbs that show up when users are running in --http mode:

That feature wouldn't make sense for users who aren't going to be using the root index.html though.

I'll open a WIP PR to show you what I've got so far and what I'm thinking.

[kernc]

I'm hesitant adding command line flags for little used features.

What do you need the index for and how often? Couldn't a simple shell script, iterating over the same packages specified on the command line, do the job?

packages="package1 package2 package3"
for pkg in $packages; do echo "<a href='$pkg'>$pkg</a><br>" >> index.html; done

What if the index were only created if the user specifies more than one package?

[kernc]

I think, rather in factly, that a proper index is indeed in order, spanning hierarchically all the way to leaf modules.

Created always.

What users specify as --output-dir is pdoc's to work with, and it shouldn't overwrite without force. I'm happy to break some integration for such nice TOC with the next major release, why not? 😃

[ryangalamb]

I'm happy to break some integration for such nice TOC with the next major release, why not?

Sounds good!

proper index is indeed in order, spanning hierarchically all the way to leaf modules.

Something sort of like this?

[kernc]

Exactly! Maybe without leading dots and more uniformly indented. Maybe with children also not necessarily exactly in the right grid column but somewhere in the middle.

[ryangalamb]

without leading dots

👍

more uniformly indented

That's straightforward enough if we style the tree as a table instead of using flexbox.

With those points, it looks more like this:

children also not necessarily exactly in the right grid column but somewhere in the middle

I'm having trouble picturing how this would look while keeping the uniform indentation. Can you show me an example of something similar to what you're expecting here?

If conserving space is your main concern, instead of showing the docstring glimpse for each submodule like I have above, we could show the top level modules like normal, and then under the description for each, we could show a more compact submodule tree without the docstrings rendered.

[kernc]

I'm having trouble picturing how this would look while keeping the uniform indentation.

No, no, I meant uniform per nesting level, as in your last image already. 👍

Just the margin is maybe a bit large here. Do subsequent <dt> need to be inside parent <dd>? Maybe we can flatten it out, apply margin per level in CSS?

[ryangalamb]

Do subsequent <dt> need to be inside parent <dd>?

Yes. As I understad, it should be a whole new <dl> inside the <dd>, since it's a different description list, and it's part of that specific description's details.

Let me give out a few options so we have something more concrete to talk about:

A) This is if I reduce the margins a bit, but keep the styling like I had in my last example

B) This is if I only indent the module docstring away from the module name

C) This is with the default dl/dt/dd display

D) This is it as nested ul/lis

Are any of these closer to what you're picturing?

[kernc]

Please excuse my slowness to respond. I get too little productive screen time these days.

I like A, C, and D. I worry D only looks good in this example, with single-line descriptions. Surprisingly, I quite like C too. A or C, your call. 👍