docs: set maxdepth or titlesonly on overly-long TOCs
#2558
Conversation
dgw
added
Documentation
Housekeeping
dgw
force-pushed
the
docs-toc-maxdepth
branch
from
57f8c27
to
30aa496
Compare
|
@SnoopJ "Back to you, Chet" to resolve or respond to the outstanding review conversations. |
There was a problem hiding this comment.
Good idea! I don't like the :hidden: option however, I prefer to have just the lvl 1 titles displayed within the body, even tho it is already displayed on the left menu column. One of the practical reason for that: the menu bar is hidden by default on mobile, and that makes it a pain to navigate.
dgw
force-pushed
the
docs-toc-maxdepth
branch
from
30aa496
to
d02f2e4
Compare
|
I lack the energy to fight for using 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 Edit 5 mins later: |
I hate you Sphinx. I really hate you. |
Didn't touch the toctree in `run.rst` because the PR expanding Sphinx install/run documentation already takes care of that one. Was going to clean up some more stuff in `index.rst` but took those out of this patch for the same reason: avoiding merge conflicts later.
Pointed to the "convenient" way of handling overlength messages via optional arguments to `bot.say()`, but also cross-referenced the bot's `safe_text_length(recipient)` method that returns the most useful value for passing a `max_length` to `get_sendable_message()`, in case plugin authors want to do something really fancy.
Without doing this, we get some very ugly Sphinx output for the class, and a few cryptic warnings about missing "class" references that are really just free-form text used in the CPython docs.
This is a supposedly "experimental" option that was added in Sphinx 4.0, but here we are using Sphinx 7.1.x and it still hasn't been added to autodoc core as planned. Turning it on fixes the display of default parameters values like `tools.memories._NO_DEFAULT` in function/method signatures. Admittedly, I have not checked through the entire documentation set again after enabling this, but it seems unlikely that there are ever cases where we want the evaluated value to display instead of how it's passed in the source code.
We have the choice of two not-great situations: 1. Concise `datetime` imports with broken cross-references in docs. 2. Verbose `datetime` imports with working cross-references in docs. The ideal, of course, would be "Concise `datetime` imports with working cross-references in docs", but this seems to be an impossibility at the current time. Forced to choose between less-than-ideal alternatives, I say we should pick the one that leads to better documentation. The cost is cheap, at just 9 extra characters in each place where `plugins.rules` references a type from sdlib's `datetime` module.
Just fixing a couple more Sphinx warnings. If only the warnings from Sphinx always looking for "class" refs even when we use type aliases in function/method signatures were this easy to solve.
dgw
force-pushed
the
docs-toc-maxdepth
branch
from
fda729a
to
8151acd
Compare
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—
maxdepthortitlesonlyoptions on TOCs where needed—this patch also cleans up some warnings generated bySopelIdentifierMemoryinheriting 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.rstabout adding install docs here is also gone; they're coming soon!Checklist
make qa(runsmake lintandmake test)make testnot so relevant, as no code changed; but I still ranmake lintsince I learned my lesson after skipping it earlier this week. 😅:py:class: reference not foundwarnings we get from using type aliases for things likeCasemappingorIdentifierFactory. Sphinx can't fix that soon enough.