search

mkdocstrings / python

A Python handler for mkdocstrings.
https://mkdocstrings.github.io/python
ISC License
190 stars 35 forks source link

fix: respect `show_root_full_path` for ToC entries #148

Closed jbott closed 5 months ago

jbott commented 7 months ago

This behavior introduced in commit 8f4c85328e8b4a45db77f9fc3e536a5008686f37 was dropped during some refactor.

pawamoy commented 7 months ago

This was actually done on purpose in 9aa758bcc42dfcf7c416d87b8f7cd407b7fdf148 (also the commit you mention does not seem to exist). The reason is that the table of content is generally quite thin and full paths are larger. Is there a specific reason why you'd like to keep showing the full path in the table of contents?

jbott commented 7 months ago

Ah, didn't see that, sorry! Also oops – dropped a leading 8 from the commit hash when submitting the PR, the correct one is 8f4c85328e8b4a45db77f9fc3e536a5008686f37 (was correct in the commit, updated the PR description as well).

I'm currently making a single-page api reference document where I'm documenting multiple modules at different module depths. Since it's all in one page, it's unclear where in the tree a context-less module name is in the ToC view.

It's internal otherwise I would share, but conceptually I'm writing something like this:

::: a.b
::: a.b.c
::: a.b.d

As-is, the ToC just displays mod a,mod b, and mod c (all at H2 level). I'm trying to get it to show mod a.b, mod a.b.c, and mod a.b.d because that disambiguates the module path (without relying on nested indent, which as you've documented, doesn't work very well since you run out of heading levels).

This might be a weird usecase, so happy to just drop this PR and maintain a patch myself, but also would be open to adding an option if that would be something you'd be open to! I think the implementation is conceptually simple – an option like show_toc_full_path would be easy enough to plumb in?

pawamoy commented 7 months ago

Thanks for the explanation :slightly_smiling_face: I'm open to an update of this PR as a feat with a show_toc_full_path option :slightly_smiling_face:

jbott commented 5 months ago

So sorry, I've gotten busy working on other things at work and haven't come back to this. I'll open a new PR with this as a feature if I do.