Closed dgw closed 7 months ago
@SnoopJ "Back to you, Chet" to resolve or respond to the outstanding review conversations.
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.
Sphinx warnings about being unable to find :py:class:
datetime
in function signatures
I hate you Sphinx. I really hate you.
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
ortitlesonly
options on TOCs where needed—this patch also cleans up some warnings generated bySopelIdentifierMemory
inheriting docstrings fromdict
, 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 oftools.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
make qa
(runsmake lint
andmake test
)make test
not so relevant, as no code changed; but I still ranmake lint
since I learned my lesson after skipping it earlier this week. 😅:py:class: reference not found
warnings we get from using type aliases for things likeCasemapping
orIdentifierFactory
. Sphinx can't fix that soon enough.