fix(docs): repair Python API cross-references

docs/README.md

@@ -44,6 +44,20 @@ When iterating on documentation, it is usually best to use the `mkdocs` commands
 * `mkdocs build` - Build the documentation site.
 * `mkdocs -h` - Print help message and exit.
 
+## Python API cross-references
+
+Python docstrings are rendered by mkdocstrings. Link to another documented Python
+object with an autorefs reference-style link whose target is the object's fully
+qualified name:
+
+```markdown
+[`DataFrame`][sedonadb.dataframe.DataFrame]
+```
+
+Backticks alone (for example, `` `DataFrame` ``) only format text as code and do
+not create a link. Sphinx roles such as `` :class:`DataFrame` `` are not supported
+by the Markdown docstring renderer.
+
 The official documentation is built using a script which may be useful when building the documentation
 locally for the first time:
 

mkdocs.yml

@@ -138,6 +138,7 @@ markdown_extensions:
    - pymdownx.tilde
 plugins:
    - search
+   - autorefs
    - macros
    - git-revision-date-localized:
         type: datetime

python/sedonadb/python/sedonadb/context.py

@@ -176,7 +176,7 @@ def create_data_frame(self, obj: Any, schema: Any = None) -> DataFrame:
         return _create_data_frame(self, obj, schema)
 
     def view(self, name: str) -> DataFrame:
-        """Create a [DataFrame][sedonadb.dataframe.DataFrame] from a named view
+        """Create a [`DataFrame`][sedonadb.dataframe.DataFrame] from a named view
 
         Refer to a named view registered with this context.
 
@@ -228,7 +228,7 @@ def read_parquet(
         validate: bool = False,
         partitioning: Union[str, Iterable[str], None] = None,
     ) -> DataFrame:
-        """Create a [DataFrame][sedonadb.dataframe.DataFrame] from one or more Parquet files
+        """Create a [`DataFrame`][sedonadb.dataframe.DataFrame] from one or more Parquet files
 
         Args:
             table_paths: A str, Path, or iterable of paths containing URLs to Parquet
@@ -381,7 +381,7 @@ def read_pyogrio(
     def sql(
         self, sql: str, *, params: Union[List, Tuple, Dict, None] = None
     ) -> DataFrame:
-        """Create a [DataFrame][sedonadb.dataframe.DataFrame] by executing SQL
+        """Create a [`DataFrame`][sedonadb.dataframe.DataFrame] by executing SQL
 
         Parses a SQL string into a logical plan and returns a DataFrame
         that can be used to request results or further modify the query.
@@ -582,7 +582,7 @@ def lit(self, value: Any) -> LiteralExpr:
 
 
 def connect() -> SedonaContext:
-    """Create a new [SedonaContext][sedonadb.context.SedonaContext]
+    """Create a new [`SedonaContext`][sedonadb.context.SedonaContext]
 
     Runtime configuration (memory limits, spill directory, pool type)
     can be set via `options` on the returned context before executing

python/sedonadb/python/sedonadb/dataframe.py

@@ -34,13 +34,22 @@
 class DataFrame:
     """Representation of a (lazy) collection of columns
 
-    This object is usually constructed from `sd = sedona.db.connect()`
-    by importing an object with `sd.create_data_frame()`, reading a file
-    with `sd.read_parquet()`/`sd.read_pyogrio()`, or executing SQL with
-    `sd.sql()`. Once created, a DataFrame can be modified using the Python
-    API (e.g., `.select()`, `.filter()`, `.sort()`, `.limit()`) or by
-    creating a temporary view with `.to_view("name")` and querying the
-    resulting view using `sd.sql()`. The Python API aims to provide
+    This object is usually constructed from a
+    [`SedonaContext`][sedonadb.context.SedonaContext], returned by
+    [`connect()`][sedonadb.context.connect], by importing an object with
+    [`create_data_frame()`][sedonadb.context.SedonaContext.create_data_frame],
+    reading a file with
+    [`read_parquet()`][sedonadb.context.SedonaContext.read_parquet] or
+    [`read_pyogrio()`][sedonadb.context.SedonaContext.read_pyogrio], or executing
+    SQL with [`sql()`][sedonadb.context.SedonaContext.sql]. Once created, a
+    DataFrame can be modified using the Python API (e.g.,
+    [`select()`][sedonadb.dataframe.DataFrame.select],
+    [`filter()`][sedonadb.dataframe.DataFrame.filter],
+    [`sort()`][sedonadb.dataframe.DataFrame.sort], or
+    [`limit()`][sedonadb.dataframe.DataFrame.limit]) or by creating a temporary
+    view with [`to_view()`][sedonadb.dataframe.DataFrame.to_view] and querying
+    the resulting view using
+    [`sql()`][sedonadb.context.SedonaContext.sql]. The Python API aims to provide
     a minimal subset of functionality derived primarily from Ibis and
     DuckDB's relational APIs.
 

python/sedonadb/python/sedonadb/read.py

@@ -184,7 +184,7 @@ def parquet(
         validate: bool = False,
         partitioning: Union[str, Iterable[str], None] = None,
     ) -> DataFrame:
-        """Create a [DataFrame][sedonadb.dataframe.DataFrame] from one or more Parquet files
+        """Create a [`DataFrame`][sedonadb.dataframe.DataFrame] from one or more Parquet files
 
         Args:
             table_paths: A str, Path, or iterable of paths containing URLs to Parquet
@@ -275,7 +275,7 @@ def csv(
         has_header: bool = True,
         delimiter: str = ",",
     ) -> DataFrame:
-        """Create a [DataFrame][sedonadb.dataframe.DataFrame] from one or more CSV files.
+        """Create a [`DataFrame`][sedonadb.dataframe.DataFrame] from one or more CSV files.
 
         The schema is inferred from the file(s). Geometry is not inferred;
         parse WKT/WKB columns explicitly (e.g. `ST_GeomFromText`) after reading.
@@ -317,7 +317,7 @@ def json(
         table_paths: Union[str, Path, Iterable[str]],
         options: Optional[Dict[str, Any]] = None,
     ) -> DataFrame:
-        """Create a [DataFrame][sedonadb.dataframe.DataFrame] from newline-delimited JSON.
+        """Create a [`DataFrame`][sedonadb.dataframe.DataFrame] from newline-delimited JSON.
 
         Reads newline-delimited JSON (NDJSON / JSON Lines) — one JSON object
         per line — not a single JSON array. The schema is inferred.