Use prune when rendering toctree to respect maxdepth

[bartek]

Note: I'm not well versed in the toctree creation here, but this change helped me get maxdepth be respected for the output. Perhaps this could be added as a configuration variable, but unsure how to do that (I can explore, but want to submit this change first to begin the conversation)

---

Prior to this, maxdepth was never respected and all headings within a document would be shown in the toctree. Now, we can have headings beyond the title in the document, that are not shown in the toctree (unless otherwise demanded through the use of maxdepth)

[KSchopmeyer]

Since there has been no action on this pr for over a year I was wondering if anybody is interested int it. We are. We like the ability to see the full toc. However since we have up to 4 levels of TOC, the sidebar gets very busy.

[bartek]

@KSchopmeyer I feel as if this project needs a new maintainer. @electrofelix are you looking to maintain this project or do you need help? Would be happy to support!

[electrofelix]

Seems reasonable, sorry not really making enough use of this these days to remember to check back here.

[electrofelix]

@dhellmann

[dhellmann]

@electrofelix Did you ping me to give @KSchopmeyer and/or @bartek maintainer access on this repository? I would be happy to do that, I just want to make sure I understand your intent.

[electrofelix]

@dhellmann I wasn't sure if you were still maintaining, figured it might be worth adding more ( I don't think I have access to merge either but probably not much point in adding me as I'm not using sphinx enough to be confident in the impact of PRS)

[dhellmann]

ok, I didn't remember who was the most recent maintainer of this. I haven't used it in a long time either.

[dhellmann]

@KSchopmeyer and @bartek I have sent you both invitations to join the sphinx-contrib org and to be maintainers of this repository. If you post your PyPI account IDs here, I will give you permission to publish releases.

@electrofelix I went ahead and added you to the repo, too, but if you don't want to be a maintainer feel free to drop it.

[bartek]

@dhellmann Ah that explains that email! Thanks.

I don't know how much spoons I have to support this repository, but I'd like to help. It's been of course a long time since I looked at this code so I'll need to find the time to revisit the PR and see if this is an appropriate approach.

I'll leave myself as a maintainer for now, and if I know I can't keep up, I will remove myself.

My PyPi id is bartekci

[dhellmann]

@bartek I have invited you on PyPI

[electrofelix]

Does anyone have an example of the difference this should be making? I tried testing it out recently and I'm not seeing that it actually has any impact, but that could be just due to my rustiness in using this.

I experimented with an old project that I had the extension in https://pypi.org/project/git-upstream/ but flipping between True/False didn't seem to impact, so I'm wondering if some other things have changed since this PR was submitted that are breaking the assumptions.

[bartek]

@electrofelix It's been awhile but IIRC, we used it on an internal project to consistently expand the toctree, rather than having it expand or collapse contextually, based on the page you were on.

To be honest, when I wrote this PR, I was just throwing code at the wall 🤦‍♂️ and the intent was to begin a conversation for a better solution. I'm happy to help explore that and ideally, write some tests while we're at it.