Improve Insertion of Kwargs into Bot Methods (#3965)

python-telegram-bot · Nov 5, 2023 · 6d2334c · 6d2334c
1 parent a0c81ec
commit 6d2334c
Show file tree

Hide file tree

Showing 2 changed files with 20 additions and 28 deletions.
diff --git a/docs/auxil/kwargs_insertion.py b/docs/auxil/kwargs_insertion.py
@@ -18,42 +18,31 @@
 import inspect
 
 keyword_args = [
+    "Keyword Arguments:",
     (
-        ":keyword _sphinx_paramlinks_telegram.Bot.{method}.read_timeout: Value to pass to "
-        ":paramref:`telegram.request.BaseRequest.post.read_timeout`. Defaults to {read_timeout}."
+        "    read_timeout ({read_timeout_type}, optional): Value to pass to "
+        "        :paramref:`telegram.request.BaseRequest.post.read_timeout`. Defaults to "
+        "        {read_timeout}."
     ),
-    ":kwtype _sphinx_paramlinks_telegram.Bot.{method}.read_timeout: {read_timeout_type}, optional",
     (
-        ":keyword _sphinx_paramlinks_telegram.Bot.{method}.write_timeout: Value to pass to "
-        ":paramref:`telegram.request.BaseRequest.post.write_timeout`. Defaults to {write_timeout}."
+        "    write_timeout (:obj:`float` | :obj:`None`, optional): Value to pass to "
+        "        :paramref:`telegram.request.BaseRequest.post.write_timeout`. Defaults to "
+        "        {write_timeout}."
     ),
     (
-        ":kwtype _sphinx_paramlinks_telegram.Bot.{method}.write_timeout: :obj:`float` |"
-        " :obj:`None`, optional"
+        "    connect_timeout (:obj:`float` | :obj:`None`, optional): Value to pass to "
+        "        :paramref:`telegram.request.BaseRequest.post.connect_timeout`. Defaults to "
+        "        :attr:`~telegram.request.BaseRequest.DEFAULT_NONE`."
     ),
     (
-        ":keyword _sphinx_paramlinks_telegram.Bot.{method}.connect_timeout: Value to pass to "
-        ":paramref:`telegram.request.BaseRequest.post.connect_timeout`. Defaults to "
-        ":attr:`~telegram.request.BaseRequest.DEFAULT_NONE`."
+        "    pool_timeout (:obj:`float` | :obj:`None`, optional): Value to pass to "
+        "        :paramref:`telegram.request.BaseRequest.post.pool_timeout`. Defaults to "
+        "        :attr:`~telegram.request.BaseRequest.DEFAULT_NONE`."
     ),
     (
-        ":kwtype _sphinx_paramlinks_telegram.Bot.{method}.connect_timeout: :obj:`float` | "
-        ":obj:`None`, optional"
+        "    api_kwargs (:obj:`dict`, optional): Arbitrary keyword arguments"
+        "        to be passed to the Telegram API."
     ),
-    (
-        ":keyword _sphinx_paramlinks_telegram.Bot.{method}.pool_timeout: Value to pass to "
-        ":paramref:`telegram.request.BaseRequest.post.pool_timeout`. Defaults to "
-        ":attr:`~telegram.request.BaseRequest.DEFAULT_NONE`."
-    ),
-    (
-        ":kwtype _sphinx_paramlinks_telegram.Bot.{method}.pool_timeout: :obj:`float` |"
-        " :obj:`None`, optional"
-    ),
-    (
-        ":keyword _sphinx_paramlinks_telegram.Bot.{method}.api_kwargs: Arbitrary keyword arguments"
-        " to be passed to the Telegram API."
-    ),
-    ":kwtype _sphinx_paramlinks_telegram.Bot.{method}.api_kwargs: :obj:`dict`, optional",
     "",
 ]
 write_timeout_sub = [":attr:`~telegram.request.BaseRequest.DEFAULT_NONE`", "``20``"]
@@ -67,7 +56,7 @@
 def find_insert_pos_for_kwargs(lines: list[str]) -> int:
     """Finds the correct position to insert the keyword arguments and returns the index."""
     for idx, value in reversed(list(enumerate(lines))):  # reversed since :returns: is at the end
-        if value.startswith(":returns:"):
+        if value.startswith("Returns"):
             return idx
     else:
         return False

diff --git a/docs/source/conf.py b/docs/source/conf.py
@@ -320,5 +320,8 @@
 def setup(app: Sphinx):
     app.connect("autodoc-skip-member", autodoc_skip_member)
     app.connect("autodoc-process-bases", autodoc_process_bases)
-    app.connect("autodoc-process-docstring", autodoc_process_docstring)
+    # The default priority is 500. We want our function to run before napoleon doc-conversion
+    # and sphinx-paramlinks do, b/c otherwise the inserted kwargs in the bot methods won't show
+    # up in the objects.inv file that Sphinx generates (i.e. not in the search).
+    app.connect("autodoc-process-docstring", autodoc_process_docstring, priority=100)
     app.add_role_to_domain("py", CONSTANTS_ROLE, TGConstXRefRole())