Feedback for the package

[choldgraf]

This is a quick issue for feedback on the UX of this package.

It would be great if folks that have lots of API docs could try the following:

1. Read the instructions / usage at https://github.com/executablebooks/sphinx-remove-toctrees#readme
2. Install the extension and activate it
3. Configure it to suppress the API docs you want out of your sidebar
4. See how it goes and report back!

Questions to answer:

• Did the UX and config make sense?
• Is this extension explained well enough?
• Is it named and described properly?

cc @jorisvandenbossche @rgommers @rossbar @stefanv @jrbourbeau in case any want to give this a shot w/ their docs.

also cc @pradyunsg and @humitos because I think this extension might be useful for the Furo / RTD themes, as it is handy for any theme that uses collapse=False.

[welcome]

Thanks for opening your first issue here! Engagement like this is essential for open source projects! 🤗

If you haven't done so already, check out EBP's Code of Conduct. Also, please try to follow the issue template as it helps other community members to contribute more effectively.

If your issue is a feature request, others may react to it, to raise its prominence (see Feature Voting).

Welcome to the EBP community! 🎉

[rgommers]

First issue: pip install git+https://github.com/executablebooks/sphinx-remove-toctree isn't working if you have 2FA enabled on GitHub, usually pointing to the tarball is the safe thing to do.

This is a new repo, so consider using main instead of master.

For the docs under Use, I wasn't sure about remove_toctrees_from - should it be a top-level entry in conf.py, or still under html_theme_options? It'd be good to be explicit there. It looks like top-level works (I tried the glob support on SciPy with remove_toctrees_from = ["reference/generated/*"]), shaved ~25% off the build time.

[choldgraf]

Thanks for these comments! I am surprised that the default branch isn't main, I thought GitHub defaulted to that now. Will investigate.

And once we get past a round of feedback i will release it on pypi, so won't need to worry about the 2FA then

[choldgraf]

@rgommers a few quick updates:

• master is now main (apparently git init locally still creates master by default, I'm not going to look for whether this is being discussed in git listservs etc because I suspect that will not be a fun conversation to watch)
• I've made a release on PyPI just to simplify things a bit for folks (I am not sure what you mean by "point to the tarball" since it's an unfamiliar pattern to what I've used, so I figured just putting it on pypi was easier :-) )
• Tried to clarify how to initialize and configure the extension a bit more

[rgommers]

Sounds great, thanks @choldgraf!

I am not sure what you mean by "point to the tarball"

GitHub gives you a stable link to just the latest sources in the repo:

In this case https://github.com/executablebooks/sphinx-remove-toctrees/archive/refs/heads/main.zip. That's easier to pip install than the weird git+ stuff that Pip requires to point to a repo.

[choldgraf]

I didn't know those were pip installable! Cool!

[pradyunsg]

master is now main (apparently git init locally still creates master by default, I'm not going to look for whether this is being discussed in git listservs etc because I suspect that will not be a fun conversation to watch)

Psst... git config --global init.defaultBranch main

[choldgraf]

I like how this issue thread has become part feedback part "teach chris how basic git and packaging works" 😅

[choldgraf]

I'm gonna assume that nobody has run into major problems with this package's UX so far? I think we should keep it as simple as possible, so I don't expect to change the configuration etc much if at all, unless there's a strong demand for something.

[pradyunsg]

I haven't tried it out yet, but the one thing that I'd suggest is changing remove_toctrees_from to remove_from_toctrees.

[jrbourbeau]

No strong demands from me : ) We started using this over Dask here dask/dask#8238