docs: improve more index-y pages

Author: tswast

bigframes/bigquery/__init__.py

@@ -12,9 +12,38 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-"""This module integrates BigQuery built-in functions for use with DataFrame objects,
-such as array functions:
-https://cloud.google.com/bigquery/docs/reference/standard-sql/array_functions. """
+"""
+Access BigQuery-specific operations and namespaces within BigQuery DataFrames.
+
+This module provides specialized functions and sub-modules that expose BigQuery's
+advanced capabilities to DataFrames and Series. It acts as a bridge between the
+pandas-compatible API and the full power of BigQuery SQL.
+
+Key sub-modules include:
+
+* :mod:`bigframes.bigquery.ai`: Generative and predictive AI functions (Gemini, BQML).
+* :mod:`bigframes.bigquery.ml`: Direct access to BigQuery ML model operations.
+* :mod:`bigframes.bigquery.obj`: Support for BigQuery object tables.
+
+This module also provides direct access to optimized BigQuery functions for:
+
+* **JSON Processing:** High-performance functions like ``json_extract``, ``json_value``,
+  and ``parse_json`` for handling semi-structured data.
+* **Geospatial Analysis:** Comprehensive geographic functions such as ``st_area``,
+  ``st_distance``, and ``st_centroid`` (``ST_`` prefixed functions).
+* **Array Operations:** Tools for working with BigQuery arrays, including ``array_agg``
+  and ``array_length``.
+* **Vector Search:** Integration with BigQuery's vector search and indexing
+  capabilities for high-dimensional data.
+* **Custom SQL:** The ``sql_scalar`` function allows embedding raw SQL snippets for
+  advanced operations not yet directly mapped in the API.
+
+By using these functions, you can leverage BigQuery's high-performance engine for
+domain-specific tasks while maintaining a Python-centric development experience.
+
+For the full list of BigQuery standard SQL functions, see:
+https://cloud.google.com/bigquery/docs/reference/standard-sql/functions-reference
+"""
 
 import sys
 

bigframes/bigquery/ai.py

@@ -12,9 +12,45 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-"""This module integrates BigQuery built-in AI functions for use with Series/DataFrame objects,
-such as AI.GENERATE_BOOL:
-https://cloud.google.com/bigquery/docs/reference/standard-sql/bigqueryml-syntax-ai-generate-bool"""
+"""
+Integrate BigQuery built-in AI functions into your BigQuery DataFrames workflow.
+
+The ``bigframes.bigquery.ai`` module provides a Pythonic interface to leverage BigQuery ML's
+generative AI and predictive functions directly on BigQuery DataFrames and Series objects.
+These functions enable you to perform advanced AI tasks at scale without moving data
+out of BigQuery.
+
+Key capabilities include:
+
+* **Generative AI:** Use :func:`bigframes.bigquery.ai.generate` (Gemini) to
+  perform text analysis, translation, or
+  content generation. Specialized versions like
+  :func:`~bigframes.bigquery.ai.generate_bool`,
+  :func:`~bigframes.bigquery.ai.generate_int`, and
+  :func:`~bigframes.bigquery.ai.generate_double` are available for structured
+  outputs.
+* **Embeddings:** Generate vector embeddings for text using
+  :func:`~bigframes.bigquery.ai.generate_embedding`, which are essential for
+  semantic search and retrieval-augmented generation (RAG) workflows.
+* **Classification and Scoring:** Apply machine learning models to your data for
+  predictive tasks with :func:`~bigframes.bigquery.ai.classify` and
+  :func:`~bigframes.bigquery.ai.score`.
+* **Forecasting:** Predict future values in time-series data using
+  :func:`~bigframes.bigquery.ai.forecast`.
+
+**Example usage:**
+
+    >>> import bigframes.pandas as bpd
+    >>> import bigframes.bigquery as bbq
+
+    >>> df = bpd.DataFrame({"text_input": ["Is this a positive review?", "The food was terrible."]})  # doctest: +SKIP
+
+    >>> # Assuming a Gemini model has been created in BigQuery as 'my_gemini_model'
+    >>> result = bq.ai.generate_text(df["text_input"], model_name="my_gemini_model")  # doctest: +SKIP
+
+For more information on the underlying BigQuery ML syntax, see:
+https://cloud.google.com/bigquery/docs/reference/standard-sql/bigqueryml-syntax-ai-generate-bool
+"""
 
 from bigframes.bigquery._operations.ai import (
     classify,

bigframes/pandas/__init__.py

@@ -12,7 +12,64 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-"""BigQuery DataFrames provides a DataFrame API backed by the BigQuery engine."""
+"""
+The primary entry point for the BigQuery DataFrames (BigFrames) pandas-compatible API.
+
+**BigQuery DataFrames** provides a Pythonic DataFrame and machine learning (ML) API
+powered by the BigQuery engine. The ``bigframes.pandas`` module implements a large
+subset of the pandas API, allowing you to perform large-scale data analysis
+using familiar pandas syntax while the computations are executed in the cloud.
+
+**Key Features:**
+
+* **Petabyte-Scale Scalability:** Handle datasets that exceed local memory by
+  offloading computation to the BigQuery distributed engine.
+* **Pandas Compatibility:** Use common pandas methods like
+  :func:`~bigframes.pandas.DataFrame.groupby`,
+  :func:`~bigframes.pandas.DataFrame.merge`,
+  :func:`~bigframes.pandas.DataFrame.pivot_table`, and more on BigQuery-backed
+  :class:`~bigframes.pandas.DataFrame` objects.
+* **Direct BigQuery Integration:** Read from and write to BigQuery tables and
+  queries with :func:`bigframes.pandas.read_gbq` and
+  :func:`bigframes.pandas.to_gbq`.
+* **User-defined Functions (UDFs):** Effortlessly deploy Python functions
+  functions using the :func:`bigframes.pandas.remote_function` and
+  :func:`bigframes.pandas.udf` decorators.
+* **Data Ingestion:** Support for various formats including CSV, Parquet, JSON,
+  and Arrow via :func:`bigrames.pandas.read_csv`,
+  :func:`bigframes.pandas.read_parquet`, etc., which are automatically uploaded
+  to BigQuery for processing. Convert any pandas DataFrame into a BigQuery
+  DataFrame using :func:`bigframes.pandas.read_pandas`.
+
+**Example usage:**
+
+    >>> import bigframes.pandas as bpd
+
+Initialize session and set options.
+
+    >>> bpd.options.bigquery.project = "your-project-id"  # doctest: +SKIP
+
+Load data from a BigQuery public dataset.
+
+    >>> df = bpd.read_gbq("bigquery-public-data.usa_names.usa_1910_2013")  # doctest: +SKIP
+
+Perform familiar pandas operations that execute in the cloud.
+
+    >>> top_names = (
+    ...     df.groupby("name")
+    ...     .agg({"number": "sum"})
+    ...     .sort_values("number", ascending=False)
+    ...     .head(10)
+    ... )  # doctest: +SKIP
+
+Bring the final, aggregated results back to local memory if needed.
+
+    >>> local_df = top_names.to_pandas()  # doctest: +SKIP
+
+BigQuery DataFrames is designed for data scientists and analysts who need the
+power of BigQuery with the ease of use of pandas. It eliminates the "data
+movement bottleneck" by keeping your data in BigQuery for processing.
+"""
 
 from __future__ import annotations
 

docs/index.rst

@@ -68,14 +68,14 @@ Explore the Documentation
     user_guide/index
 
 .. toctree::
-    :maxdepth: 3
+    :maxdepth: 2
     :caption: API Reference
 
     reference/index
     supported_pandas_apis
 
 .. toctree::
-    :maxdepth: 2
+    :maxdepth: 1
     :caption: Community & Updates
 
     changelog