From 9a99d41a5439dd8092ad1cb63e197f45281c608f Mon Sep 17 00:00:00 2001
From: Anthony DiGirolamo <tonymd@google.com>
Date: Wed, 12 Jun 2024 21:00:05 +0000
Subject: [PATCH] docs: Fix Python package dependencies for sphinx
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The docs build was depending on the top level "python.install" that
pip installs all Pigweed python packages. This CL removes that and
insteads adds them to python_deps. This will improve build times
slightly and remove the dependency on having a bootstrapped
environment working to run the docs build.

Change-Id: I08e85a81531faa40f46b09b48414e8799731c426
Reviewed-on: https://pigweed-review.googlesource.com/c/pigweed/pigweed/+/215852
Commit-Queue: Anthony DiGirolamo <tonymd@google.com>
Lint: Lint 🤖 <android-build-ayeaye@system.gserviceaccount.com>
Reviewed-by: Wyatt Hepler <hepler@google.com>
---
 docs/BUILD.gn         |  8 ++++----
 pw_docgen/docs.gni    | 27 +++++++++++++++++++++------
 pw_metric/py/BUILD.gn |  1 +
 3 files changed, 26 insertions(+), 10 deletions(-)

diff --git a/docs/BUILD.gn b/docs/BUILD.gn
index 76da552eb..55bca4ecd 100644
--- a/docs/BUILD.gn
+++ b/docs/BUILD.gn
@@ -356,10 +356,10 @@ pw_doc_gen("docs") {
     ":third_party_docs",
     "$dir_pigweed/kudzu:docs",
     "$dir_pigweed/seed:seeds",
-    "$dir_pw_env_setup:python.install",
   ]
 
-  # Required to set the PYTHONPATH so automodule, autoclass or autofunction RST
-  # directives work.
-  python_metadata_deps = [ "$dir_pw_env_setup:core_pigweed_python_packages" ]
+  # Extra Python deps are required to set the PYTHONPATH so
+  # automodule, autoclass or autofunction RST directives work in
+  # sphinx.
+  python_deps = [ "$dir_pw_env_setup:core_pigweed_python_packages" ]
 }
diff --git a/pw_docgen/docs.gni b/pw_docgen/docs.gni
index ed157f914..18f795133 100644
--- a/pw_docgen/docs.gni
+++ b/pw_docgen/docs.gni
@@ -77,10 +77,17 @@ template("pw_doc_group") {
 #
 # Args:
 #   deps: List of pw_doc_group targets.
-#   python_metadata_deps: Python-related dependencies that are only used as deps
-#                         for generating Python package metadata list, not the
-#                         overall documentation generation. This should rarely
-#                         be used by non-Pigweed code.
+#   python_deps: Additional Python package dependencies that must be
+#                fully built before sphinx can run. This will set the
+#                PYTHONPATH when sphinx is run so automodule,
+#                autoclass or autofunction RST directives work for
+#                in-tree pw_python_package targets.
+#   python_metadata_deps: Python-related dependencies that are only
+#                         used as deps for generating Python package
+#                         metadata list, not the overall documentation
+#                         generation. This only modifies PYTHONPATH so
+#                         sphinx can import in-tree Python files. This
+#                         should rarely be used by non-Pigweed code.
 #   sources: Top-level documentation .rst source files.
 #   conf: Configuration script (conf.py) for Sphinx.
 #   output_directory: Path to directory to which HTML output is rendered.
@@ -148,8 +155,16 @@ template("pw_doc_gen") {
       python_deps = [ "$dir_pw_docgen/py" ]
       deps = [ ":$_metadata_file_target" ]
 
-      # Required to set the PYTHONPATH for any automodule/class/function RST
-      # directives.
+      # Additional Python deps that may be required for sphinx to run
+      # successfully. These deps will be fully built.
+      if (defined(invoker.python_deps)) {
+        python_deps += invoker.python_deps
+      }
+
+      # Required to set the PYTHONPATH for any automodule, autoclass,
+      # and autofunction RST directives. These deps will have their
+      # in-tree directories added to PYTHONPATH only. They will not be
+      # generated or built in the out directory first.
       python_metadata_deps = [ "$dir_pw_docgen/py" ]
       if (defined(invoker.python_metadata_deps)) {
         python_metadata_deps += invoker.python_metadata_deps
diff --git a/pw_metric/py/BUILD.gn b/pw_metric/py/BUILD.gn
index e7afa3480..ace24b2ee 100644
--- a/pw_metric/py/BUILD.gn
+++ b/pw_metric/py/BUILD.gn
@@ -31,6 +31,7 @@ pw_python_package("py") {
   python_deps = [
     "$dir_pw_rpc/py",
     "$dir_pw_tokenizer/py",
+    "..:metric_service_proto.python",
   ]
   python_test_deps = [ "$dir_pw_metric:metric_service_proto.python" ]
   pylintrc = "$dir_pigweed/.pylintrc"