From 7498726aef6ed81d2ce3da325c89857b6dbc03ca Mon Sep 17 00:00:00 2001
From: Quentin Pradet <quentin.pradet@elastic.co>
Date: Fri, 14 Feb 2025 22:40:46 +0400
Subject: [PATCH] Explain how to use sub clients in API docs (#2798)

(cherry picked from commit db22037da287063c1c00f7d2dfc26a8945ff5de5)
---
 docs/sphinx/api/elasticsearch.rst |  2 +-
 docs/sphinx/conf.py               | 34 ++++++++++++++++++++++++++++++-
 elasticsearch/client.py           |  2 ++
 3 files changed, 36 insertions(+), 2 deletions(-)

diff --git a/docs/sphinx/api/elasticsearch.rst b/docs/sphinx/api/elasticsearch.rst
index 64df4540b..b8831a407 100644
--- a/docs/sphinx/api/elasticsearch.rst
+++ b/docs/sphinx/api/elasticsearch.rst
@@ -3,7 +3,7 @@
 Elasticsearch
 -------------
 
-.. py:module:: elasticsearch.client
+.. py:module:: elasticsearch
 
 .. autoclass:: Elasticsearch
    :members:
diff --git a/docs/sphinx/conf.py b/docs/sphinx/conf.py
index 7104660b5..d1537932b 100644
--- a/docs/sphinx/conf.py
+++ b/docs/sphinx/conf.py
@@ -21,10 +21,42 @@
 
 extensions = ["sphinx.ext.autodoc", "sphinx.ext.doctest", "sphinx.ext.intersphinx"]
 
-autoclass_content = "both"
+autoclass_content = "class"
+autodoc_class_signature = "separated"
 
 autodoc_typehints = "description"
 
+
+def client_name(full_name):
+    # Get the class name, e.g. ['elasticsearch', 'client', 'TextStructureClient'] -> 'TextStructure'
+    class_name = full_name.split(".")[-1].removesuffix("Client")
+    # Convert to snake case, e.g. 'TextStructure' -> '_text_structure'
+    snake_case = "".join(["_" + c.lower() if c.isupper() else c for c in class_name])
+    # Remove the leading underscore
+    return snake_case.lstrip("_")
+
+
+def add_client_usage_example(app, what, name, obj, options, lines):
+    if what == "class" and "Client" in name:
+        sub_client_name = client_name(name)
+        lines.append(
+            f"To use this client, access ``client.{sub_client_name}`` from an "
+            " :class:`~elasticsearch.Elasticsearch` client. For example::"
+        )
+        lines.append("")
+        lines.append("    from elasticsearch import Elasticsearch")
+        lines.append("")
+        lines.append("    # Create the client instance")
+        lines.append("    client = Elasticsearch(...)")
+        lines.append(f"    # Use the {sub_client_name} client")
+        lines.append(f"    client.{sub_client_name}.<method>(...)")
+        lines.append("")
+
+
+def setup(app):
+    app.connect("autodoc-process-docstring", add_client_usage_example)
+
+
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ["_templates"]
 
diff --git a/elasticsearch/client.py b/elasticsearch/client.py
index af25c5ae1..926ed5fe3 100644
--- a/elasticsearch/client.py
+++ b/elasticsearch/client.py
@@ -73,6 +73,8 @@
 from ._utils import fixup_module_metadata
 
 # This file exists for backwards compatibility.
+# We can't remove it as we use it for the Sphinx docs which show the full page, and we'd
+# rather show `elasticsearch.client.FooClient` than `elasticsearch._sync.client.FooClient`.
 warnings.warn(
     "Importing from the 'elasticsearch.client' module is deprecated. "
     "Instead use 'elasticsearch' module for importing the client.",