sopel-irc / sopel

:robot::speech_balloon: An easy-to-use and highly extensible IRC Bot framework. Formerly Willie.
https://sopel.chat
Other
951 stars 405 forks source link

docs: set `maxdepth` or `titlesonly` on overly-long TOCs #2558

Closed dgw closed 7 months ago

dgw commented 7 months ago

Description

I set out to clean up some of the documentation appearance & make things more usable, taking into consideration the fact that we use the Furo theme now and detailed in-page TOCs are kinda redundant in a lot of places thanks to the dual sidebars.

In addition to the original impetus for this patch—maxdepth or titlesonly options on TOCs where needed—this patch also cleans up some warnings generated by SopelIdentifierMemory inheriting docstrings from dict, tells autodoc not to evaluate function argument defaults before display (eliminates <class 'sopel.foo.nonsense.ClassName'> from being shown, which is very ugly), and also improves the docstring of tools.get_sendable_message() because I don't want to open a tiny PR for that.

I'm also aware of what #2533 plans to change, and therefore avoided touching any of that PR's renamed/modified rST files at all. The comment in index.rst about adding install docs here is also gone; they're coming soon!

Checklist

dgw commented 7 months ago

@SnoopJ "Back to you, Chet" to resolve or respond to the outstanding review conversations.

dgw commented 7 months ago

I lack the energy to fight for using :hidden: in a few selected locations, so the win goes to @Exirel.

Latest branch update added a fix for Sphinx warnings about being unable to find :py:class:`datetime` in function signatures, as well. Now we have "only" 18 warnings (14 from that pesky issue with type aliases; 2 for internals of ast; and 2 for bad links to ssl.wrap_socket, which I might try to fix next also fixed).

Edit 5 mins later: wrap_socket warnings fixed. That was too easy. Down to 16 warnings now, which will have to do.

Exirel commented 7 months ago

Sphinx warnings about being unable to find :py:class:datetime in function signatures

I hate you Sphinx. I really hate you.