Internal change

PiperOrigin-RevId: 858231029
2026-01-24 10:53:30 +08:00 · 2026-01-19 18:25:54 +00:00
parent f931c4a5e7
commit 8679637161
6 changed files with 134 additions and 86 deletions
--- a/doc/python/sphinx/_static/custom.css
+++ b/doc/python/sphinx/_static/custom.css
@@ -1,43 +1,38 @@
-dl.field-list > dt {
-    word-break: keep-all !important;
-}
-.document {
-  width: 90% !important;
-  margin: 0 auto;
-  display: flex;
-}
-.sphinxsidebar {
-    overflow-y: scroll;
-    top: 0;
-    bottom: 0;
-    width: 35% !important;
-    flex-shrink: 0 !important;
-    min-width: 340px !important;
-    position: unset !important;
-}
-.bodywrapper {
-  margin: auto !important;
-}
-.body {
-  max-width: 100% !important;
-  min-width: 800px !important;
-}
-.footer {
-  margin: 20px 50px 30px auto !important;
+html[data-theme="dark"] {
+  --pst-color-target: color-mix(in srgb, var(--pst-color-surface), purple 10%)
 }

-@media (max-width: 875px) {
-  .document {
-    flex-direction: column;
+/* Sidebar Widths */
+.bd-sidebar-primary {
+  width: 17%;
+}
+
+.bd-sidebar-secondary {
+  width: 30%;
+}
+
+@media (max-width: 960px) {
+
+  /* Ensure long function/method signatures wrap on mobile */
+  dt.sig {
+    white-space: normal !important;
+    overflow-wrap: break-word !important;
+    word-break: break-all !important;
+    /* Force break for very long identifiers */
  }
-  .sphinxsidebar {
-    width: 100% !important;
-    background: white !important;
-  }
-  .sphinxsidebar a {
-    color: #444 !important;
-  }
-  .sphinxsidebar h3, .sphinxsidebar h4, .sphinxsidebar p, .sphinxsidebar h3 a {
-    color: #444 !important;
+
+  /* Add a bit of indentation for wrapped lines to keep them readable */
+  dt.sig-object {
+    padding-left: 1em;
+    text-indent: -1em;
+  }
+}
+
+/* Mobile Sidebar Widths */
+@media (max-width: 960px) {
+
+  .bd-sidebar-primary,
+  .bd-sidebar-secondary {
+    width: 75% !important;
  }
 }
--- a/doc/python/sphinx/_templates/sidebar-nav-bs.html
+++ b/doc/python/sphinx/_templates/sidebar-nav-bs.html
@@ -0,0 +1,29 @@
+{# Displays the TOC-subtree for pages nested under the currently active #}
+{# top-level TOCtree element. #}
+{# Overriding default sidebar-nav-bs.html with startdepth=0 to show all aux #}
+{# package pages in the sidebar #}
+{# Note: `startdepth=0` is the only custom change, rest of the definition is #}
+{# taken from
+https://github.com/pydata/pydata-sphinx-theme/blob/a892bfad42c83db158fcc3d658c6677d532094bf/src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/sidebar-nav-bs.html
+#}
+
+{%- if meta is defined and meta is not none and 'html_theme.show_nav_level' in meta -%}
+{%- set show_nav_level = meta['html_theme.show_nav_level'] -%}
+{%- else -%}
+{%- set show_nav_level = theme_show_nav_level -%}
+{%- endif -%}
+<nav class="bd-docs-nav bd-links" aria-label="{{ _('Section Navigation') }}">
+  <p class="bd-links__title" role="heading" aria-level="1">{{ _("Section Navigation") }}</p>
+  <div class="bd-toc-item navbar-nav">
+    {{- generate_toctree_html(
+    "sidebar",
+    startdepth=0,
+    show_nav_level=show_nav_level | int,
+    maxdepth=theme_navigation_depth | int,
+    collapse=theme_collapse_navigation | tobool,
+    includehidden=theme_sidebar_includehidden | tobool,
+    titles_only=True
+    )
+    -}}
+  </div>
+</nav>
--- a/doc/python/sphinx/conf.py
+++ b/doc/python/sphinx/conf.py
@@ -16,14 +16,20 @@

 import os
 import sys
+
+# Add all packages to sys.path
 PYTHON_FOLDER = os.path.join(os.path.dirname(os.path.realpath(__file__)), '..',
                             '..', '..', 'src', 'python')
-sys.path.insert(0, os.path.join(PYTHON_FOLDER, 'grpcio'))
-sys.path.insert(0, os.path.join(PYTHON_FOLDER, 'grpcio_channelz'))
-sys.path.insert(0, os.path.join(PYTHON_FOLDER, 'grpcio_health_checking'))
-sys.path.insert(0, os.path.join(PYTHON_FOLDER, 'grpcio_reflection'))
-sys.path.insert(0, os.path.join(PYTHON_FOLDER, 'grpcio_status'))
-sys.path.insert(0, os.path.join(PYTHON_FOLDER, 'grpcio_testing'))
+ALL_PACKAGES = [
+    'grpcio', 'grpcio_admin', 'grpcio_channelz', 'grpcio_csds',
+    'grpcio_health_checking', 'grpcio_observability',
+    'grpcio_reflection', 'grpcio_status', 'grpcio_testing'
+]
+for pkg in ALL_PACKAGES:
+    # Use .append() instead of insert(0) to let Sphinx find the compiled
+    # Cython extensions from site-packages correctly
+    sys.path.append(os.path.join(PYTHON_FOLDER, pkg))
+

 # -- Project information -----------------------------------------------------

@@ -74,16 +80,27 @@ autodoc_typehints = 'description'

 # -- HTML Configuration -------------------------------------------------

-html_theme = 'alabaster'
+html_theme = 'pydata_sphinx_theme'
+html_title = f"gRPC Python Docs v{version}"
 html_theme_options = {
-    'fixed_sidebar': True,
-    'page_width': 'auto',
-    'show_related': True,
-    'analytics_id': 'UA-60127042-1',
-    'description': grpc_version.VERSION,
-    'show_powered_by': False,
+    "navbar_center": [],
+    "header_links_before_dropdown": 15,
+    "secondary_sidebar_items": ["page-toc", "edit-this-page"],
+    "show_toc_level": 2,
 }
+
+html_theme_options["analytics"] = {
+    "google_analytics_id": "UA-60127042-1",
+}
+
+html_sidebars = {
+    "**": ["sidebar-nav-bs"]
+}
+
 html_static_path = ["_static"]
+html_css_files = [
+    "custom.css"
+]

 # -- Options for manual page output ------------------------------------------

--- a/doc/python/sphinx/index.rst
+++ b/doc/python/sphinx/index.rst
@@ -7,7 +7,7 @@ API Reference
 =============

 .. toctree::
-   :caption: Contents:
+   :maxdepth: 2

   grpc
   grpc_asyncio
--- a/tools/distrib/docgen/_generate_python_doc.sh
+++ b/tools/distrib/docgen/_generate_python_doc.sh
@@ -31,6 +31,7 @@ tools/run_tests/run_tests.py -c opt -l python --compiler python3.9 --newline_on_
 # shellcheck disable=SC1091
 source py39/bin/activate
 pip install --upgrade Sphinx
+pip install pydata_sphinx_theme==0.16.1

 # Use direct sphinx-build CLI command instead of `python setup.py doc`
 sphinx-build -b html -W --keep-going "$SOURCE_DIR" "$TARGET_DIR"
--- a/tools/distrib/docgen/requirements.docs.lock
+++ b/tools/distrib/docgen/requirements.docs.lock
@@ -1,41 +1,47 @@
 # GRPC Python setup requirements
 # The requirements listed below are used to generated API reference documentation.
-absl-py==1.4.0
-cachetools==5.3.2
-certifi==2023.7.22
-chardet==3.0.4
-charset-normalizer==3.3.2
+# This file is currently not generated. It is a copy of an old requirements.
+# bazel.lock file as of https://github.com/grpc/grpc/pull/38616 with
+# manually updated versions.
+# TODO(ssreenithi): create a separate requirements.docs.txt file with only
+# required packages for docgen and regenerate this file. Tech debt from:
+# https://github.com/grpc/grpc/pull/38616
+absl-py==2.1.0
+cachetools==5.5.1
+certifi==2025.1.31
+chardet==5.2.0
+charset-normalizer==3.4.1
 coverage==4.5.4
 cython==3.1.1
-Deprecated==1.2.14
-gevent==22.08.0
-google-api-core==2.24.0
-google-auth==2.23.4
-google-cloud-monitoring==2.26.0
-google-cloud-trace==1.15.0
-googleapis-common-protos==1.63.1
-greenlet==1.1.3.post0
-idna==2.7
-importlib-metadata==6.11.0
-oauth2client==4.1.0
+deprecated==1.2.18
+gevent==25.9.1
+google-api-core==2.28.1
+google-auth==2.38.0
+google-cloud-monitoring==2.28.0
+google-cloud-trace==1.17.0
+googleapis-common-protos==1.72.0
+greenlet==3.2.4
+idna==3.10
+importlib-metadata==8.5.0
+oauth2client==4.1.3
 opencensus-context==0.1.3
-opentelemetry-api==1.25.0
-opentelemetry-exporter-prometheus==0.46b0
-opentelemetry-resourcedetector-gcp==1.6.0a0
-opentelemetry-sdk==1.25.0
-opentelemetry-semantic-conventions==0.46b0
-prometheus_client==0.20.0
-proto-plus==1.25.0
-protobuf>=5.27.1,<6.0.0
-pyasn1-modules==0.3.0
-pyasn1==0.5.0
-requests==2.25.1
+opentelemetry-api==1.30.0
+opentelemetry-exporter-prometheus==0.51b0
+opentelemetry-resourcedetector-gcp==1.9.0a0
+opentelemetry-sdk==1.30.0
+opentelemetry-semantic-conventions==0.51b0
+prometheus-client==0.21.1
+proto-plus==1.27.0
+protobuf==6.33.2
+pyasn1==0.6.1
+pyasn1-modules==0.4.1
+requests==2.32.3
 rsa==4.9
 setuptools==77.0.1
-typing-extensions==4.9.0
-urllib3==1.26.18
-wheel==0.38.1
-wrapt==1.16.0
-zipp==3.17.0
-zope.event==4.5.0
-zope.interface==6.1
+typing-extensions==4.12.2
+urllib3==2.2.3
+wheel==0.46.1
+wrapt==1.17.2
+zipp==3.20.2
+zope-event==5.0
+zope-interface==7.2