Control: tags -1 + patch
On 13/01/2025 12:59, Stuart Prescott wrote:
The error «(SEVERE/4) Unexpected section title.» is about the Parameters
and Returns headings that are inserted into the API docs (running sphinx
with `-v -v -v` revealed that).
There is on-the-fly manipulation of the docstrings in jupyter_client/
client.py::reqrep - I was able to get the docs to build by changing the
inserted Parameters and Returns into paragraphs rather than headings.
I've attached a patch that does this. I don't think it's quite the right
change to be making, but it might help someone else understand the
problem and find a better solution.
An alternative way to fixing this is to remove all the whitespace
indentation in the jupyter_client/client.py::reqrep function. That lets
the build complete with the headings intact... the output seems to be as
intended.
Stuart
--
Stuart Prescott http://www.nanonanonano.net/ stu...@nanonanonano.net
Debian Developer http://www.debian.org/ stu...@debian.org
GPG fingerprint 90E2 D2C1 AD14 6A1B 7EBB 891D BBC1 7EBB 1396 F2F7
From: Stuart Prescott <stu...@debian.org>
Date: Mon, 13 Jan 2025 12:43:57 +1100
Subject: Unindent headings in docstrings
---
jupyter_client/client.py | 27 ++++++++++++++-------------
1 file changed, 14 insertions(+), 13 deletions(-)
diff --git a/jupyter_client/client.py b/jupyter_client/client.py
index 851a234..7bbcb01 100644
--- a/jupyter_client/client.py
+++ b/jupyter_client/client.py
@@ -47,23 +47,24 @@ def reqrep(wrapped: t.Callable, meth: t.Callable, channel: str = "shell") -> t.C
if "Parameters" not in basedoc:
parts.append(
"""
- Parameters
- ----------
+Parameters
+----------
"""
)
parts.append(
"""
- reply: bool (default: False)
- Whether to wait for and return reply
- timeout: float or None (default: None)
- Timeout to use when waiting for a reply
-
- Returns
- -------
- msg_id: str
- The msg_id of the request sent, if reply=False (default)
- reply: dict
- The reply message for this request, if reply=True
+reply: bool (default: False)
+ Whether to wait for and return reply
+timeout: float or None (default: None)
+ Timeout to use when waiting for a reply
+
+Returns
+-------
+
+msg_id: str
+ The msg_id of the request sent, if reply=False (default)
+reply: dict
+ The reply message for this request, if reply=True
"""
)
wrapped.__doc__ = "\n".join(parts)
