sphinx ext: include autosummary templates and extensions from cookiecutter-scverse

[ilia-kats]

This moves the autosummary templates and custom Sphinx extensions from cookiecutter-scverse into our own Sphinx extension. See also the discussion in scverse/cookiecutter-scverse#483.

[codecov]

Codecov Report

❌ Patch coverage is 92.72727% with 4 lines in your changes missing coverage. Please review.
✅ Project coverage is 93.26%. Comparing base (a1e1f01) to head (d423a0f).
⚠️ Report is 2 commits behind head on main.

Files with missing lines	Patch %	Lines
src/scverse_misc/sphinx_ext/__init__.py	92.72%	4 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main      #60      +/-   ##
==========================================
- Coverage   93.28%   93.26%   -0.02%     
==========================================
  Files          11       11              
  Lines         536      579      +43     
==========================================
+ Hits          500      540      +40     
- Misses         36       39       +3     

Files with missing lines	Coverage Δ
src/scverse_misc/sphinx_ext/__init__.py	89.06% <92.72%> (+1.14%)	⬆️

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[grst]

I don't see any issues from the technical side.
I think some lines would need to be added to the scverse_misc docs to describe this additional functionality of the sphinx extension, how to enable it, and why this is needed.

[ilia-kats]

I've added some docs. I would love to get rid of our own _templates/autosummary/class.rst and just dogfood, but that template contains a workaround for sphinx-doc/sphinx#14515, which we need. I'm also happy to include the workaround in the shipped template file or try to fix napoleon's _skip_member and ship the fixed version here until it's released as part of Sphinx.

[grst]

• Once this is merged, can't we update the template to use scverse_misc and get rid of all custom sphinx extensions there?
• Keeping the workaround until it's fixed upstream sounds reasonable. Maybe we can also track it in a ticket in scverse_misc so we don't forget to remove it eventually.

[ilia-kats]

Once this is merged, can't we update the template to use scverse_misc and get rid of all custom sphinx extensions there?

That's the plan, isn't it?

[grst]

It is, but what do you mean by this then?

I'm also happy to include the workaround in the shipped template file

[ilia-kats]

So scverse_misc currently has two sets of templates: One in docs/_templates, which was inherited from the cookiecutter template and is currently used to build the scverse_misc docs, and one in src/scverse_misc/sphinx_ext/templates (added in this PR), which will be used by downstream packages. The former contains the workaround (introduced in #40), the latter does not. So we can either also apply the workaround to the sphinx_ext template, or I attempt to fix the napoleon bug and make the fix part of our sphinx extension.

[grst]

IIUC, this bug only affects a minority of repos that want to document "special" functions with sphinx autodocs.
In that case I would keep the workaround in the local docs/_template fix and leave the sphinx_ext umodified and work on the napoleon fix in parallel.

[flying-sheep]

we should document that we do this (and what “this” is).

[ilia-kats]

Done. Not sure if that one sentence is enough, but the cookiecutter thing wasn't documented at all, so better than it used to be, I guess?