Update documentation to cross reference

timsaucer · timsaucer · commit 61b6a69e0670 · 2024-07-28T11:24:31.000-04:00
diff --git a/docs/source/conf.py b/docs/source/conf.py
@@ -46,8 +46,8 @@
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
 extensions = [
-    "sphinx.ext.autodoc",
-    "sphinx.ext.autosummary",
+    # "sphinx.ext.autodoc",
+    # "sphinx.ext.autosummary",
     "sphinx.ext.doctest",
     "sphinx.ext.ifconfig",
     "sphinx.ext.mathjax",
diff --git a/docs/source/user-guide/basics.rst b/docs/source/user-guide/basics.rst
@@ -54,7 +54,7 @@ The first statement group:
     # create a context
     ctx = datafusion.SessionContext()
 
-creates a :code:`SessionContext`, that is, the main interface for executing queries with DataFusion. It maintains the state
+creates a :py:class:`~datafusion.context.SessionContext`, that is, the main interface for executing queries with DataFusion. It maintains the state
 of the connection between a user and an instance of the DataFusion engine. Additionally it provides the following functionality:
 
 - Create a DataFrame from a CSV or Parquet data source.
@@ -74,9 +74,9 @@ The second statement group creates a :code:`DataFrame`,
     df = ctx.create_dataframe([[batch]])
 
 A DataFrame refers to a (logical) set of rows that share the same column names, similar to a `Pandas DataFrame <https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.DataFrame.html>`_.
-DataFrames are typically created by calling a method on :code:`SessionContext`, such as :code:`read_csv`, and can then be modified by
-calling the transformation methods, such as :meth:`.DataFrame.filter`, :meth:`.DataFrame.select`, :meth:`.DataFrame.aggregate`,
-and :meth:`.DataFrame.limit` to build up a query definition.
+DataFrames are typically created by calling a method on :py:class:`~datafusion.context.SessionContext`, such as :code:`read_csv`, and can then be modified by
+calling the transformation methods, such as :py:func:`~datafusion.dataframe.DataFrame.filter`, :py:func:`~datafusion.dataframe.DataFrame.select`, :py:func:`~datafusion.dataframe.DataFrame.aggregate`,
+and :py:func:`~datafusion.dataframe.DataFrame.limit` to build up a query definition.
 
 The third statement uses :code:`Expressions` to build up a query definition.
 
@@ -87,5 +87,5 @@ The third statement uses :code:`Expressions` to build up a query definition.
         col("a") - col("b"),
     )
 
-Finally the :code:`collect` method converts the logical plan represented by the DataFrame into a physical plan and execute it,
-collecting all results into a list of `RecordBatch <https://arrow.apache.org/docs/python/generated/pyarrow.RecordBatch.html>`_.
+Finally the :py:func:`~datafusion.dataframe.DataFrame.collect` method converts the logical plan represented by the DataFrame into a physical plan and execute it,
+collecting all results into a list of `RecordBatch <https://arrow.apache.org/docs/python/generated/pyarrow.RecordBatch.html>`_.
diff --git a/docs/source/user-guide/common-operations/aggregations.rst b/docs/source/user-guide/common-operations/aggregations.rst
@@ -19,7 +19,7 @@ Aggregation
 ============
 
 An aggregate or aggregation is a function where the values of multiple rows are processed together to form a single summary value.
-For performing an aggregation, DataFusion provides the :meth:`.DataFrame.aggregate`
+For performing an aggregation, DataFusion provides the :py:func:`~datafusion.dataframe.DataFrame.aggregate`
 
 .. ipython:: python
 
diff --git a/docs/source/user-guide/common-operations/basic-info.rst b/docs/source/user-guide/common-operations/basic-info.rst
@@ -34,26 +34,26 @@ In this section, you will learn how to display essential details of DataFrames u
     })
     df
 
-Use :meth:`.DataFrame.limit` to view the top rows of the frame:
+Use :py:func:`~datafusion.dataframe.DataFrame.limit` to view the top rows of the frame:
 
 .. ipython:: python
 
     df.limit(2)
 
-Display the columns of the DataFrame using :meth:`.DataFrame.schema`:
+Display the columns of the DataFrame using :py:func:`~datafusion.dataframe.DataFrame.schema`:
 
 .. ipython:: python
 
     df.schema()
 
-The method :meth:`.DataFrame.to_pandas` uses pyarrow to convert to pandas DataFrame, by collecting the batches,
+The method :py:func:`~datafusion.dataframe.DataFrame.to_pandas` uses pyarrow to convert to pandas DataFrame, by collecting the batches,
 passing them to an Arrow table, and then converting them to a pandas DataFrame.
 
 .. ipython:: python
 
     df.to_pandas()
 
-:meth:`.DataFrame.describe` shows a quick statistic summary of your data:
+:py:func:`~datafusion.dataframe.DataFrame.describe` shows a quick statistic summary of your data:
 
 .. ipython:: python
 
diff --git a/docs/source/user-guide/common-operations/expressions.rst b/docs/source/user-guide/common-operations/expressions.rst
@@ -28,16 +28,16 @@ concept shared across most compilers and databases.
 Column
 ------
 
-The first expression most new users will interact with is the Column, which is created by calling :func:`col`.
-This expression represents a column within a DataFrame. The function :func:`col` takes as in input a string
+The first expression most new users will interact with is the Column, which is created by calling :py:func:`~datafusion.col`.
+This expression represents a column within a DataFrame. The function :py:func:`~datafusion.col` takes as in input a string
 and returns an expression as it's output.
 
 Literal
 -------
 
 Literal expressions represent a single value. These are helpful in a wide range of operations where
-a specific, known value is of interest. You can create a literal expression using the function :func:`lit`.
-The type of the object passed to the :func:`lit` function will be used to convert it to a known data type.
+a specific, known value is of interest. You can create a literal expression using the function :py:func:`~datafusion.lit`.
+The type of the object passed to the :py:func:`~datafusion.lit` function will be used to convert it to a known data type.
 
 In the following example we create expressions for the column named `color` and the literal scalar string `red`.
 The resultant variable `red_units` is itself also an expression.
@@ -64,7 +64,7 @@ Functions
 ---------
 
 As mentioned before, most functions in DataFusion return an expression at their output. This allows us to create
-a wide variety of expressions built up from other expressions. For example, :func:`.alias` is a function that takes
+a wide variety of expressions built up from other expressions. For example, :py:func:`~datafusion.expr.Expr.alias` is a function that takes
 as it input a single expression and returns an expression in which the name of the expression has changed.
 
 The following example shows a series of expressions that are built up from functions operating on expressions.
diff --git a/docs/source/user-guide/common-operations/functions.rst b/docs/source/user-guide/common-operations/functions.rst
@@ -40,7 +40,7 @@ We'll use the pokemon dataset in the following examples.
 Mathematical
 ------------
 
-DataFusion offers mathematical functions such as :func:`.pow` or :func:`.log`
+DataFusion offers mathematical functions such as :py:func:`~datafusion.functions.pow` or :py:func:`~datafusion.functions.log`
 
 .. ipython:: python
 
@@ -55,7 +55,7 @@ DataFusion offers mathematical functions such as :func:`.pow` or :func:`.log`
 Conditional
 -----------
 
-There 3 conditional functions in DataFusion :func:`.coalesce`, :func:`.nullif` and :func:`.case` (not available in Python)
+There 3 conditional functions in DataFusion :py:func:`~datafusion.functions.coalesce`, :py:func:`~datafusion.functions.nullif` and :py:func:`~datafusion.functions.case`.
 
 .. ipython:: python
 
@@ -66,13 +66,13 @@ There 3 conditional functions in DataFusion :func:`.coalesce`, :func:`.nullif` a
 Temporal
 --------
 
-For selecting the current time use :func:`.now`
+For selecting the current time use :py:func:`~datafusion.functions.now`
 
 .. ipython:: python
 
     df.select(f.now())
 
-Convert to timestamps using :func:`.to_timestamp`
+Convert to timestamps using :py:func:`~datafusion.functions.to_timestamp`
 
 .. ipython:: python
 
@@ -92,7 +92,7 @@ DataFusion offers a range of helpful options.
         f.left(col('"Name"'), literal(4)).alias("code")
     )
 
-This also includes the functions for regular expressions like :func:`.regexp_replace` and :func:`.regexp_match`
+This also includes the functions for regular expressions like :py:func:`~datafusion.functions.regexp_replace` and :py:func:`~datafusion.functions.regexp_match`
 
 .. ipython:: python
 
@@ -105,7 +105,7 @@ This also includes the functions for regular expressions like :func:`.regexp_rep
 Other
 -----
 
-The function :func:`.in_list` allows to check a column for the presence of multiple values:
+The function :py:func:`~datafusion.functions.in_list` allows to check a column for the presence of multiple values:
 
 .. ipython:: python
 
diff --git a/docs/source/user-guide/common-operations/joins.rst b/docs/source/user-guide/common-operations/joins.rst
@@ -18,7 +18,7 @@
 Joins
 =====
 
-DataFusion supports the following join variants via the method :meth:`.DataFrame.join`
+DataFusion supports the following join variants via the method :py:func:`~datafusion.dataframe.DataFrame.join`
 
 - Inner Join
 - Left Join
@@ -58,7 +58,7 @@ will be included in the resulting DataFrame.
 
     left.join(right, join_keys=(["customer_id"], ["id"]), how="inner")
 
-The parameter :code:`join_keys` specifies the columns from the left DataFrame and right DataFrame that contains the values
+The parameter ``join_keys`` specifies the columns from the left DataFrame and right DataFrame that contains the values
 that should match.
 
 Left Join
diff --git a/docs/source/user-guide/common-operations/select-and-filter.rst b/docs/source/user-guide/common-operations/select-and-filter.rst
@@ -18,7 +18,7 @@
 Column Selections
 =================
 
-Use :meth:`.DataFrame.select_columns`  for basic column selection.
+Use :py:func:`~datafusion.dataframe.DataFrame.select`  for basic column selection.
 
 DataFusion can work with several file types, to start simple we can use a subset of the 
 `TLC Trip Record Data <https://www.nyc.gov/site/tlc/about/tlc-trip-record-data.page>`_
@@ -35,8 +35,8 @@ DataFusion can work with several file types, to start simple we can use a subset
     df = ctx.read_parquet("yellow_trip_data.parquet")
     df.select_columns("trip_distance", "passenger_count")
 
-For mathematical or logical operations use :func:`.col` to select columns, and give meaningful names to the resulting
-operations using :func:`.alias`
+For mathematical or logical operations use :py:func:`~datafusion.col` to select columns, and give meaningful names to the resulting
+operations using :py:func:`~datafusion.expr.Expr.alias`
 
 
 .. ipython:: python
@@ -48,7 +48,7 @@ operations using :func:`.alias`
 
     Please be aware that all identifiers are effectively made lower-case in SQL, so if your file has capital letters
     (ex: Name) you must put your column name in double quotes or the selection won’t work. As an alternative for simple
-    column selection use :meth:`.DataFrame.select_columns` without double quotes
+    column selection use :py:func:`~datafusion.dataframe.DataFrame.select_columns` without double quotes
 
 For selecting columns with capital letters use ``'"VendorID"'``
 
@@ -57,7 +57,7 @@ For selecting columns with capital letters use ``'"VendorID"'``
     df.select(col('"VendorID"'))
 
 
-To combine it with literal values use the :func:`.lit`
+To combine it with literal values use the :py:func:`~datafusion.lit`
 
 .. ipython:: python
 
diff --git a/docs/source/user-guide/common-operations/udf-and-udfa.rst b/docs/source/user-guide/common-operations/udf-and-udfa.rst
@@ -19,7 +19,7 @@ User Defined Functions
 ======================
 
 DataFusion provides powerful expressions and functions, reducing the need for custom Python functions.
-However you can still incorporate your own functions, i.e. User-Defined Functions (UDFs), with the :func:`.udf` function.
+However you can still incorporate your own functions, i.e. User-Defined Functions (UDFs), with the :py:func:`~datafusion.udf.ScalarUDF.udf` function.
 
 .. ipython:: python
 
@@ -42,7 +42,7 @@ However you can still incorporate your own functions, i.e. User-Defined Function
 
     df.select(is_null_arr(col("a"))).to_pandas()
 
-Additionally the :func:`.udaf` function allows you to define User-Defined Aggregate Functions (UDAFs)
+Additionally the :py:func:`~datafusion.udf.AggregateUDF.udaf` function allows you to define User-Defined Aggregate Functions (UDAFs)
 
 .. code-block:: python
 
diff --git a/docs/source/user-guide/common-operations/windows.rst b/docs/source/user-guide/common-operations/windows.rst
@@ -21,7 +21,7 @@ Window Functions
 In this section you will learn about window functions. A window function utilizes values from one or multiple rows to
 produce a result for each individual row, unlike an aggregate function that provides a single value for multiple rows.
 
-The functionality of window functions in DataFusion is supported by the dedicated :func:`.window` function.
+The functionality of window functions in DataFusion is supported by the dedicated :py:func:`~datafusion.functions.window` function.
 
 We'll use the pokemon dataset (from Ritchie Vink) in the following examples.
 
@@ -40,7 +40,7 @@ We'll use the pokemon dataset (from Ritchie Vink) in the following examples.
     ctx = SessionContext()
     df = ctx.read_csv("pokemon.csv")
 
-Here is an example that shows how to compare each pokemons’s attack power with the average attack power in its :code:`"Type 1"`
+Here is an example that shows how to compare each pokemons’s attack power with the average attack power in its ``"Type 1"``
 
 .. ipython:: python
 
@@ -54,7 +54,7 @@ Here is an example that shows how to compare each pokemons’s attack power with
     )
 
 You can also control the order in which rows are processed by window functions by providing
-a list of :func:`.order_by` functions for the :code:`order_by` parameter.
+a list of ``order_by`` functions for the ``order_by`` parameter.
 
 .. ipython:: python
 
diff --git a/docs/source/user-guide/configuration.rst b/docs/source/user-guide/configuration.rst
@@ -18,8 +18,8 @@
 Configuration
 =============
 
-Let's look at how we can configure DataFusion. When creating a :code:`SessionContext`, you can pass in
-a :code:`SessionConfig` and :code:`RuntimeConfig` object. These two cover a wide range of options.
+Let's look at how we can configure DataFusion. When creating a :py:class:`~datafusion.context.SessionContext`, you can pass in
+a :py:class:`~datafusion.context.SessionConfig` and :py:class:`~datafusion.context.RuntimeConfig` object. These two cover a wide range of options.
 
 .. code-block:: python
 
@@ -47,5 +47,5 @@ a :code:`SessionConfig` and :code:`RuntimeConfig` object. These two cover a wide
     print(ctx)
 
 
-You can read more about available :code:`SessionConfig` options in the `rust DataFusion Configuration guide <https://arrow.apache.org/datafusion/user-guide/configs.html>`_,
+You can read more about available :py:class:`~datafusion.context.SessionConfig` options in the `rust DataFusion Configuration guide <https://arrow.apache.org/datafusion/user-guide/configs.html>`_,
 and about :code:`RuntimeConfig` options in the rust `online API documentation <https://docs.rs/datafusion/latest/datafusion/execution/runtime_env/struct.RuntimeConfig.html>`_.
diff --git a/docs/source/user-guide/io/avro.rst b/docs/source/user-guide/io/avro.rst
@@ -19,7 +19,7 @@ Avro
 ====
 
 `Avro <https://avro.apache.org/>`_ is a serialization format for record data. Reading an avro file is very straightforward
-with :meth:`.SessionContext.read_avro`
+with :py:func:`~datafusion.context.SessionContext.read_avro`
 
 .. code-block:: python
 
diff --git a/docs/source/user-guide/io/csv.rst b/docs/source/user-guide/io/csv.rst
@@ -18,7 +18,7 @@
 CSV
 ===
 
-Reading a csv is very straightforward with :meth:`.SessionContext.read_csv`
+Reading a csv is very straightforward with :py:func:`~datafusion.context.SessionContext.read_csv`
 
 .. code-block:: python
 
@@ -28,9 +28,9 @@ Reading a csv is very straightforward with :meth:`.SessionContext.read_csv`
     ctx = SessionContext()
     df = ctx.read_csv("file.csv")
 
-An alternative is to use :meth:`.SessionContext.register_csv`
+An alternative is to use :py:func:`~datafusion.context.SessionContext.register_csv`
 
 .. code-block:: python
 
     ctx.register_csv("file", "file.csv")
-    df = ctx.table("file")
+    df = ctx.table("file")
diff --git a/docs/source/user-guide/io/json.rst b/docs/source/user-guide/io/json.rst
@@ -18,7 +18,7 @@
 JSON
 ====
 `JSON <https://www.json.org/json-en.html>`_ (JavaScript Object Notation) is a lightweight data-interchange format.
-When it comes to reading a JSON file, using :meth:`.SessionContext.read_json` is a simple and easy
+When it comes to reading a JSON file, using :py:func:`~datafusion.context.SessionContext.read_json` is a simple and easy
 
 .. code-block:: python
 
diff --git a/docs/source/user-guide/io/parquet.rst b/docs/source/user-guide/io/parquet.rst
@@ -18,7 +18,7 @@
 Parquet
 =======
 
-It is quite simple to read a parquet file using the :meth:`.SessionContext.read_parquet` function.
+It is quite simple to read a parquet file using the :py:func:`~datafusion.context.SessionContext.read_parquet` function.
 
 .. code-block:: python
 
@@ -28,9 +28,9 @@ It is quite simple to read a parquet file using the :meth:`.SessionContext.read_
     ctx = SessionContext()
     df = ctx.read_parquet("file.parquet")
 
-An alternative is to use :meth:`.SessionContext.register_parquet`
+An alternative is to use :py:func:`~datafusion.context.SessionContext.register_parquet`
 
 .. code-block:: python
 
     ctx.register_parquet("file", "file.parquet")
-    df = ctx.table("file")
+    df = ctx.table("file")
diff --git a/python/datafusion/__init__.py b/python/datafusion/__init__.py
@@ -63,7 +63,9 @@
     "ScalarUDF",
     "WindowFrame",
     "column",
+    "col",
     "literal",
+    "lit",
     "DFSchema",
 ]
 
@@ -73,15 +75,20 @@ def column(value: str):
     return Expr.column(value)
 
 
-col = column
+def col(value: str):
+    """Create a column expression."""
+    return Expr.column(value)
 
 
 def literal(value):
     """Create a literal expression."""
     return Expr.literal(value)
 
 
-lit = literal
+def lit(value):
+    """Create a literal expression."""
+    return Expr.literal(value)
+
 
 udf = ScalarUDF.udf
 
diff --git a/python/datafusion/dataframe.py b/python/datafusion/dataframe.py
@@ -506,7 +506,7 @@ def count(self) -> int:
         """
         return self.df.count()
 
-    @deprecated("Use :func:`unnest_columns` instead.")
+    @deprecated("Use :py:func:`unnest_columns` instead.")
     def unnest_column(self, column: str, preserve_nulls: bool = True) -> DataFrame:
         """See :py:func:`unnest_columns`."""
         return DataFrame(self.df.unnest_column(column, preserve_nulls=preserve_nulls))
diff --git a/python/datafusion/functions.py b/python/datafusion/functions.py
diff --git a/python/datafusion/udf.py b/python/datafusion/udf.py
