sphinx ext: include autosummary templates and extensions from cookiecutter-scverse by ilia-kats · Pull Request #60 · scverse/scverse-misc

ilia-kats · 2026-07-01T13:08:20Z

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.

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 · 2026-07-01T13:09:09Z

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 · 2026-07-01T15:17:32Z

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 · 2026-07-02T09:05:41Z

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 · 2026-07-02T09:16:23Z

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 · 2026-07-02T09:18:32Z

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 · 2026-07-02T10:49:25Z

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 · 2026-07-02T11:13:04Z

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 · 2026-07-02T12:37:41Z

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 · 2026-07-03T13:20:28Z

+ yield line
+
+
+def _parse_returns_section(self: NumpyDocstring, section: str) -> list[str]:


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

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?

ilia-kats · 2026-07-01T13:08:20Z

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.

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 · 2026-07-01T13:09:09Z

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 · 2026-07-01T15:17:32Z

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 · 2026-07-02T09:05:41Z

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 · 2026-07-02T09:16:23Z

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 · 2026-07-02T09:18:32Z

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 · 2026-07-02T10:49:25Z

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 · 2026-07-02T11:13:04Z

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 · 2026-07-02T12:37:41Z

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 · 2026-07-03T13:20:28Z

+ yield line
+
+
+def _parse_returns_section(self: NumpyDocstring, section: str) -> list[str]:


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

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?

ilia-kats · 2026-07-01T13:08:20Z

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.

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 · 2026-07-01T13:09:09Z

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 · 2026-07-01T15:17:32Z

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 · 2026-07-02T09:05:41Z

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 · 2026-07-02T09:16:23Z

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 · 2026-07-02T09:18:32Z

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 · 2026-07-02T10:49:25Z

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 · 2026-07-02T11:13:04Z

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 · 2026-07-02T12:37:41Z

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 · 2026-07-03T13:20:28Z

+ yield line
+
+
+def _parse_returns_section(self: NumpyDocstring, section: str) -> list[str]:


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

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?

ilia-kats · 2026-07-01T13:08:20Z

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.

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 · 2026-07-01T13:09:09Z

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 · 2026-07-01T15:17:32Z

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 · 2026-07-02T09:05:41Z

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 · 2026-07-02T09:16:23Z

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 · 2026-07-02T09:18:32Z

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 · 2026-07-02T10:49:25Z

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 · 2026-07-02T11:13:04Z

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 · 2026-07-02T12:37:41Z

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 · 2026-07-03T13:20:28Z

+ yield line
+
+
+def _parse_returns_section(self: NumpyDocstring, section: str) -> list[str]:


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

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?

ilia-kats · 2026-07-01T13:08:20Z

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.

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 · 2026-07-01T13:09:09Z

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 · 2026-07-01T15:17:32Z

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 · 2026-07-02T09:05:41Z

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 · 2026-07-02T09:16:23Z

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 · 2026-07-02T09:18:32Z

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 · 2026-07-02T10:49:25Z

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 · 2026-07-02T11:13:04Z

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 · 2026-07-02T12:37:41Z

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 · 2026-07-03T13:20:28Z

+ yield line
+
+
+def _parse_returns_section(self: NumpyDocstring, section: str) -> list[str]:


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

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?

ilia-kats · 2026-07-01T13:08:20Z

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.

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 · 2026-07-01T13:09:09Z

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 · 2026-07-01T15:17:32Z

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 · 2026-07-02T09:05:41Z

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 · 2026-07-02T09:16:23Z

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 · 2026-07-02T09:18:32Z

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 · 2026-07-02T10:49:25Z

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 · 2026-07-02T11:13:04Z

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 · 2026-07-02T12:37:41Z

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 · 2026-07-03T13:20:28Z

+ yield line
+
+
+def _parse_returns_section(self: NumpyDocstring, section: str) -> list[str]:


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

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?

ilia-kats · 2026-07-01T13:08:20Z

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.

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 · 2026-07-01T13:09:09Z

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 · 2026-07-01T15:17:32Z

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 · 2026-07-02T09:05:41Z

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 · 2026-07-02T09:16:23Z

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 · 2026-07-02T09:18:32Z

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 · 2026-07-02T10:49:25Z

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 · 2026-07-02T11:13:04Z

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 · 2026-07-02T12:37:41Z

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 · 2026-07-03T13:20:28Z

+ yield line
+
+
+def _parse_returns_section(self: NumpyDocstring, section: str) -> list[str]:


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

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?

ilia-kats · 2026-07-01T13:08:20Z

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.

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 · 2026-07-01T13:09:09Z

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 · 2026-07-01T15:17:32Z

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 · 2026-07-02T09:05:41Z

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 · 2026-07-02T09:16:23Z

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 · 2026-07-02T09:18:32Z

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 · 2026-07-02T10:49:25Z

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 · 2026-07-02T11:13:04Z

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 · 2026-07-02T12:37:41Z

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 · 2026-07-03T13:20:28Z

+ yield line
+
+
+def _parse_returns_section(self: NumpyDocstring, section: str) -> list[str]:


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

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?

ilia-kats added 2 commits July 1, 2026 15:07

include autosummary templates in sphinx extension
c708051
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

add skip_private_bases
1550950

ilia-kats requested review from flying-sheep and grst July 1, 2026 13:08

fix tests
da5c93e

add documentation and changelog entry
bb12426

flying-sheep reviewed Jul 2, 2026
View reviewed changes

Comment threadtests/test_sphinx.py
Comment threadsrc/scverse_misc/sphinx_ext/__init__.py

ilia-kats added 2 commits July 3, 2026 15:03

correctly process prose return sections
a27e473

more tests for _member_type
64e84c3

flying-sheep approved these changes Jul 3, 2026
View reviewed changes

ilia-kats added 2 commits July 3, 2026 15:25

fixup! correctly process prose return sections
578880c

document
2c1fc93

flying-sheep reviewed Jul 3, 2026
View reviewed changes

Comment threadtests/deprecation_decorator/test_sphinx.py Outdated

remove stray print
d423a0f

ilia-kats enabled auto-merge (squash) July 3, 2026 14:04

ilia-kats merged commit 3632417 into mainJul 3, 2026
12 checks passed

ilia-kats deleted the autosummary_templates branch July 3, 2026 14:06

ilia-kats mentioned this pull request Jul 4, 2026
pydocstring doesn’t preserve prose return sections #57
Closed

This was referenced Aug 25, 2026
Common documentation/docstring related utlities #12
Open
move generic docs stuff to scverse-doc? #78
Open

ilia-kats added 2 commits July 1, 2026 15:07

include autosummary templates in sphinx extension
c708051
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

add skip_private_bases
1550950

ilia-kats requested review from flying-sheep and grst July 1, 2026 13:08

fix tests
da5c93e

add documentation and changelog entry
bb12426

flying-sheep reviewed Jul 2, 2026
View reviewed changes

Comment threadtests/test_sphinx.py
Comment threadsrc/scverse_misc/sphinx_ext/__init__.py

ilia-kats added 2 commits July 3, 2026 15:03

correctly process prose return sections
a27e473

more tests for _member_type
64e84c3

flying-sheep approved these changes Jul 3, 2026
View reviewed changes

ilia-kats added 2 commits July 3, 2026 15:25

fixup! correctly process prose return sections
578880c

document
2c1fc93

flying-sheep reviewed Jul 3, 2026
View reviewed changes

Comment threadtests/deprecation_decorator/test_sphinx.py Outdated

remove stray print
d423a0f

ilia-kats enabled auto-merge (squash) July 3, 2026 14:04

ilia-kats merged commit 3632417 into mainJul 3, 2026
12 checks passed

ilia-kats deleted the autosummary_templates branch July 3, 2026 14:06

ilia-kats mentioned this pull request Jul 4, 2026
pydocstring doesn’t preserve prose return sections #57
Closed

This was referenced Aug 25, 2026
Common documentation/docstring related utlities #12
Open
move generic docs stuff to scverse-doc? #78
Open

ilia-kats added 2 commits July 1, 2026 15:07

include autosummary templates in sphinx extension
c708051
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

add skip_private_bases
1550950

ilia-kats requested review from flying-sheep and grst July 1, 2026 13:08

fix tests
da5c93e

add documentation and changelog entry
bb12426

flying-sheep reviewed Jul 2, 2026
View reviewed changes

Comment threadtests/test_sphinx.py
Comment threadsrc/scverse_misc/sphinx_ext/__init__.py

ilia-kats added 2 commits July 3, 2026 15:03

correctly process prose return sections
a27e473

more tests for _member_type
64e84c3

flying-sheep approved these changes Jul 3, 2026
View reviewed changes

ilia-kats added 2 commits July 3, 2026 15:25

fixup! correctly process prose return sections
578880c

document
2c1fc93

flying-sheep reviewed Jul 3, 2026
View reviewed changes

Comment threadtests/deprecation_decorator/test_sphinx.py Outdated

remove stray print
d423a0f

ilia-kats enabled auto-merge (squash) July 3, 2026 14:04

ilia-kats merged commit 3632417 into mainJul 3, 2026
12 checks passed

ilia-kats deleted the autosummary_templates branch July 3, 2026 14:06

ilia-kats mentioned this pull request Jul 4, 2026
pydocstring doesn’t preserve prose return sections #57
Closed

This was referenced Aug 25, 2026
Common documentation/docstring related utlities #12
Open
move generic docs stuff to scverse-doc? #78
Open

ilia-kats added 2 commits July 1, 2026 15:07

include autosummary templates in sphinx extension
c708051
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

add skip_private_bases
1550950

ilia-kats requested review from flying-sheep and grst July 1, 2026 13:08

fix tests
da5c93e

add documentation and changelog entry
bb12426

flying-sheep reviewed Jul 2, 2026
View reviewed changes

Comment threadtests/test_sphinx.py
Comment threadsrc/scverse_misc/sphinx_ext/__init__.py

ilia-kats added 2 commits July 3, 2026 15:03

correctly process prose return sections
a27e473

more tests for _member_type
64e84c3

flying-sheep approved these changes Jul 3, 2026
View reviewed changes

ilia-kats added 2 commits July 3, 2026 15:25

fixup! correctly process prose return sections
578880c

document
2c1fc93

flying-sheep reviewed Jul 3, 2026
View reviewed changes

Comment threadtests/deprecation_decorator/test_sphinx.py Outdated

remove stray print
d423a0f

ilia-kats enabled auto-merge (squash) July 3, 2026 14:04

ilia-kats merged commit 3632417 into mainJul 3, 2026
12 checks passed

ilia-kats deleted the autosummary_templates branch July 3, 2026 14:06

ilia-kats mentioned this pull request Jul 4, 2026
pydocstring doesn’t preserve prose return sections #57
Closed

This was referenced Aug 25, 2026
Common documentation/docstring related utlities #12
Open
move generic docs stuff to scverse-doc? #78
Open

ilia-kats added 2 commits July 1, 2026 15:07

include autosummary templates in sphinx extension
c708051
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

add skip_private_bases
1550950

ilia-kats requested review from flying-sheep and grst July 1, 2026 13:08

fix tests
da5c93e

add documentation and changelog entry
bb12426

flying-sheep reviewed Jul 2, 2026
View reviewed changes

Comment threadtests/test_sphinx.py
Comment threadsrc/scverse_misc/sphinx_ext/__init__.py

ilia-kats added 2 commits July 3, 2026 15:03

correctly process prose return sections
a27e473

more tests for _member_type
64e84c3

flying-sheep approved these changes Jul 3, 2026
View reviewed changes

ilia-kats added 2 commits July 3, 2026 15:25

fixup! correctly process prose return sections
578880c

document
2c1fc93

flying-sheep reviewed Jul 3, 2026
View reviewed changes

Comment threadtests/deprecation_decorator/test_sphinx.py Outdated

remove stray print
d423a0f

ilia-kats enabled auto-merge (squash) July 3, 2026 14:04

ilia-kats merged commit 3632417 into mainJul 3, 2026
12 checks passed

ilia-kats deleted the autosummary_templates branch July 3, 2026 14:06

ilia-kats mentioned this pull request Jul 4, 2026
pydocstring doesn’t preserve prose return sections #57
Closed

This was referenced Aug 25, 2026
Common documentation/docstring related utlities #12
Open
move generic docs stuff to scverse-doc? #78
Open

ilia-kats added 2 commits July 1, 2026 15:07

include autosummary templates in sphinx extension
c708051
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

add skip_private_bases
1550950

ilia-kats requested review from flying-sheep and grst July 1, 2026 13:08

fix tests
da5c93e

add documentation and changelog entry
bb12426

flying-sheep reviewed Jul 2, 2026
View reviewed changes

Comment threadtests/test_sphinx.py
Comment threadsrc/scverse_misc/sphinx_ext/__init__.py

ilia-kats added 2 commits July 3, 2026 15:03

correctly process prose return sections
a27e473

more tests for _member_type
64e84c3

flying-sheep approved these changes Jul 3, 2026
View reviewed changes

ilia-kats added 2 commits July 3, 2026 15:25

fixup! correctly process prose return sections
578880c

document
2c1fc93

flying-sheep reviewed Jul 3, 2026
View reviewed changes

Comment threadtests/deprecation_decorator/test_sphinx.py Outdated

remove stray print
d423a0f

ilia-kats enabled auto-merge (squash) July 3, 2026 14:04

ilia-kats merged commit 3632417 into mainJul 3, 2026
12 checks passed

ilia-kats deleted the autosummary_templates branch July 3, 2026 14:06

ilia-kats mentioned this pull request Jul 4, 2026
pydocstring doesn’t preserve prose return sections #57
Closed

This was referenced Aug 25, 2026
Common documentation/docstring related utlities #12
Open
move generic docs stuff to scverse-doc? #78
Open

ilia-kats added 2 commits July 1, 2026 15:07

include autosummary templates in sphinx extension
c708051
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

add skip_private_bases
1550950

ilia-kats requested review from flying-sheep and grst July 1, 2026 13:08

fix tests
da5c93e

add documentation and changelog entry
bb12426

flying-sheep reviewed Jul 2, 2026
View reviewed changes

Comment threadtests/test_sphinx.py
Comment threadsrc/scverse_misc/sphinx_ext/__init__.py

ilia-kats added 2 commits July 3, 2026 15:03

correctly process prose return sections
a27e473

more tests for _member_type
64e84c3

flying-sheep approved these changes Jul 3, 2026
View reviewed changes

ilia-kats added 2 commits July 3, 2026 15:25

fixup! correctly process prose return sections
578880c

document
2c1fc93

flying-sheep reviewed Jul 3, 2026
View reviewed changes

Comment threadtests/deprecation_decorator/test_sphinx.py Outdated

remove stray print
d423a0f

ilia-kats enabled auto-merge (squash) July 3, 2026 14:04

ilia-kats merged commit 3632417 into mainJul 3, 2026
12 checks passed

ilia-kats deleted the autosummary_templates branch July 3, 2026 14:06

ilia-kats mentioned this pull request Jul 4, 2026
pydocstring doesn’t preserve prose return sections #57
Closed

This was referenced Aug 25, 2026
Common documentation/docstring related utlities #12
Open
move generic docs stuff to scverse-doc? #78
Open

ilia-kats added 2 commits July 1, 2026 15:07

include autosummary templates in sphinx extension
c708051
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

add skip_private_bases
1550950

ilia-kats requested review from flying-sheep and grst July 1, 2026 13:08

fix tests
da5c93e

add documentation and changelog entry
bb12426

flying-sheep reviewed Jul 2, 2026
View reviewed changes

Comment threadtests/test_sphinx.py
Comment threadsrc/scverse_misc/sphinx_ext/__init__.py

ilia-kats added 2 commits July 3, 2026 15:03

correctly process prose return sections
a27e473

more tests for _member_type
64e84c3

flying-sheep approved these changes Jul 3, 2026
View reviewed changes

ilia-kats added 2 commits July 3, 2026 15:25

fixup! correctly process prose return sections
578880c

document
2c1fc93

flying-sheep reviewed Jul 3, 2026
View reviewed changes

Comment threadtests/deprecation_decorator/test_sphinx.py Outdated

remove stray print
d423a0f

ilia-kats enabled auto-merge (squash) July 3, 2026 14:04

ilia-kats merged commit 3632417 into mainJul 3, 2026
12 checks passed

ilia-kats deleted the autosummary_templates branch July 3, 2026 14:06

ilia-kats mentioned this pull request Jul 4, 2026
pydocstring doesn’t preserve prose return sections #57
Closed

This was referenced Aug 25, 2026
Common documentation/docstring related utlities #12
Open
move generic docs stuff to scverse-doc? #78
Open

		yield line


		def _parse_returns_section(self: NumpyDocstring, section: str) -> list[str]:

Uh oh!

Conversation

ilia-kats commented Jul 1, 2026

Uh oh!

codecovBot commented Jul 1, 2026• edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

grst commented Jul 1, 2026

Uh oh!

ilia-kats commented Jul 2, 2026

Uh oh!

grst commented Jul 2, 2026

Uh oh!

ilia-kats commented Jul 2, 2026

Uh oh!

grst commented Jul 2, 2026

Uh oh!

ilia-kats commented Jul 2, 2026• edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

grst commented Jul 2, 2026

Uh oh!

Uh oh!

Uh oh!

flying-sheepJul 3, 2026

Choose a reason for hiding this comment

Uh oh!

ilia-katsJul 3, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Uh oh!

Conversation

ilia-kats commented Jul 1, 2026

Uh oh!

codecovBot commented Jul 1, 2026• edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

grst commented Jul 1, 2026

Uh oh!

ilia-kats commented Jul 2, 2026

Uh oh!

grst commented Jul 2, 2026

Uh oh!

ilia-kats commented Jul 2, 2026

Uh oh!

grst commented Jul 2, 2026

Uh oh!

ilia-kats commented Jul 2, 2026• edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

grst commented Jul 2, 2026

Uh oh!

Uh oh!

Uh oh!

flying-sheepJul 3, 2026

Choose a reason for hiding this comment

Uh oh!

ilia-katsJul 3, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

codecovBot commented Jul 1, 2026•
edited
Loading

ilia-kats commented Jul 2, 2026•
edited
Loading

codecovBot commented Jul 1, 2026•
edited
Loading

ilia-kats commented Jul 2, 2026•
edited
Loading

codecovBot commented Jul 1, 2026•
edited
Loading

ilia-kats commented Jul 2, 2026•
edited
Loading

codecovBot commented Jul 1, 2026•
edited
Loading