From d86e73187c3e5454f6bca109eb79465f9967015b Mon Sep 17 00:00:00 2001
From: Doug Davis <ddavis@anaconda.com>
Date: Thu, 7 Sep 2023 13:47:43 -0500
Subject: [PATCH 1/3] docs for from_text

---
 docs/api/io.rst                 |  2 +-
 docs/how-to/io.rst              | 18 ++++++++----------
 src/dask_awkward/lib/io/text.py | 31 +++++++++++++++++++++++++++++--
 3 files changed, 38 insertions(+), 13 deletions(-)

diff --git a/docs/api/io.rst b/docs/api/io.rst
index 9c0023c0..e2789fcf 100644
--- a/docs/api/io.rst
+++ b/docs/api/io.rst
@@ -13,6 +13,7 @@ IO
    from_lists
    from_map
    from_parquet
+   from_text
    to_dask_array
    to_dask_bag
    to_dataframe
@@ -20,7 +21,6 @@ IO
    to_parquet
    to_json
 
-
 .. raw:: html
 
    <script data-goatcounter="https://dask-awkward.goatcounter.com/count"
diff --git a/docs/how-to/io.rst b/docs/how-to/io.rst
index 94e5cca9..8af35365 100644
--- a/docs/how-to/io.rst
+++ b/docs/how-to/io.rst
@@ -3,7 +3,8 @@ Data IO
 
 Creating dask-awkward collections typically begins with reading from
 either local disk or cloud storage. There is built-in support for
-datasets stored in Parquet or JSON format.
+datasets stored in Parquet or JSON format, along support for reading
+text files with each line treated as an element of an array.
 
 Take this code-block for example:
 
@@ -11,15 +12,12 @@ Take this code-block for example:
 
    >>> import dask_awkward as dak
    >>> ds1 = dak.from_parquet("s3://path/to/dataset")
-   >>> ds2 = dak.from_json("/path/to/json-files/*.json")
-
-Both the :py:func:`~dask_awkward.from_parquet` and
-:func:`~dask_awkward.from_json` calls will create new
-:class:`dask_awkward.Array` instances. In the Parquet example we will
-read data from Amazon S3; in the JSON example we're reading data from
-local disk (notice the wildcard syntax: all JSON files in that
-directory will be discovered, and each file will become a partition in
-the collection).
+   >>> ds2 = dak.from_json("/path/to/json-files")
+   >>> ds3 = dak.from_text("s3://some/text/*.txt")
+
+In the Parquet and text examples we will read data from Amazon S3; in
+the JSON example we're reading data from local disk. These collections
+will partitioned on a per-file basis
 
 Support for the ROOT file format is provided by the Uproot_ project.
 
diff --git a/src/dask_awkward/lib/io/text.py b/src/dask_awkward/lib/io/text.py
index 93e3394f..8802cedf 100644
--- a/src/dask_awkward/lib/io/text.py
+++ b/src/dask_awkward/lib/io/text.py
@@ -57,13 +57,40 @@ def from_text(
     source: str | list[str],
     blocksize: str | int = "128 MiB",
     delimiter: bytes = b"\n",
-    sample_size: str | int = "128 KiB",
     compression: str | None = "infer",
     storage_options: dict | None = None,
 ) -> Array:
+    """Read text data as array of strings; each line an element.
+
+    Parameters
+    ----------
+    source : str | list[str]
+        Data source as a list of files or a single path (can be remote
+        files).
+    blocksize : str | int
+        Size of each partition in bytes.
+    delimiter : bytes
+        Delimiter to separate elements of the array (default is
+        newline character).
+    compression : str, optional
+        Compression of the files for reading (default is to infer).
+    storage_options : dict, optional
+        Storage options passed to the ``fsspec`` filesystem.
+
+    Returns
+    -------
+    Array
+        Resulting collection.
+
+    Examples
+    --------
+    >>> import dask_awkward as dak
+    >>> dak.from_text("s3://path/to/files", blocksize="256 MiB")
+
+    """
     fs, token, paths = get_fs_token_paths(source, storage_options=storage_options or {})
 
-    token = tokenize(source, token, blocksize, delimiter, sample_size)
+    token = tokenize(source, token, blocksize, delimiter, compression)
 
     if compression == "infer":
         compression = infer_compression(paths[0])

From 1fb652c59f9da755d81c24d720f56c33bc80ad07 Mon Sep 17 00:00:00 2001
From: Doug Davis <ddavis@anaconda.com>
Date: Thu, 7 Sep 2023 13:48:59 -0500
Subject: [PATCH 2/3] example

---
 src/dask_awkward/lib/io/text.py | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/dask_awkward/lib/io/text.py b/src/dask_awkward/lib/io/text.py
index 8802cedf..6df8265e 100644
--- a/src/dask_awkward/lib/io/text.py
+++ b/src/dask_awkward/lib/io/text.py
@@ -85,7 +85,7 @@ def from_text(
     Examples
     --------
     >>> import dask_awkward as dak
-    >>> dak.from_text("s3://path/to/files", blocksize="256 MiB")
+    >>> dak.from_text("s3://path/to/files/*.txt", blocksize="256 MiB")
 
     """
     fs, token, paths = get_fs_token_paths(source, storage_options=storage_options or {})

From 173daba6d8da42f57d1dc88c2484fc8a7493c470 Mon Sep 17 00:00:00 2001
From: Doug Davis <ddavis@anaconda.com>
Date: Thu, 7 Sep 2023 14:00:20 -0500
Subject: [PATCH 3/3] docs

---
 docs/conf.py                    | 1 +
 docs/how-to/io.rst              | 2 +-
 docs/more/optimization.rst      | 4 ++++
 pyproject.toml                  | 1 +
 src/dask_awkward/lib/core.py    | 2 +-
 src/dask_awkward/lib/io/text.py | 7 +++++--
 6 files changed, 13 insertions(+), 4 deletions(-)

diff --git a/docs/conf.py b/docs/conf.py
index a5541a8d..690d5fc7 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -44,6 +44,7 @@
     "sphinx.ext.todo",
     "sphinx.ext.autosectionlabel",
     "sphinx_design",
+    "sphinx_codeautolink",
 ]
 
 # Add any paths that contain templates here, relative to this directory.
diff --git a/docs/how-to/io.rst b/docs/how-to/io.rst
index 8af35365..2db7cad6 100644
--- a/docs/how-to/io.rst
+++ b/docs/how-to/io.rst
@@ -17,7 +17,7 @@ Take this code-block for example:
 
 In the Parquet and text examples we will read data from Amazon S3; in
 the JSON example we're reading data from local disk. These collections
-will partitioned on a per-file basis
+will be partitioned on a per-file basis
 
 Support for the ROOT file format is provided by the Uproot_ project.
 
diff --git a/docs/more/optimization.rst b/docs/more/optimization.rst
index 74d45dd2..8aea9ee0 100644
--- a/docs/more/optimization.rst
+++ b/docs/more/optimization.rst
@@ -59,6 +59,7 @@ If our task graph is of the form:
 
 .. code:: pycon
 
+   >>> import dask_awkward as dak
    >>> ds = dak.from_parquet("/path/to/data")
    >>> result = ds.bar.x / ds.foo
 
@@ -103,6 +104,7 @@ necessary columns):
 
 .. code:: pycon
 
+   >>> import dask_awkward as dak
    >>> dak.necessary_columns(result)
    {"some-layer-name": ["foo", "bar.x"]}
 
@@ -131,6 +133,8 @@ above example, we write
 
 .. code:: pycon
 
+   >>> import dask_awkward as dak
+   >>> import dask.config
    >>> ds = dak.from_parquet("/path/to/data", columns=["bar.x", "foo"])
    >>> result = ds.bar.x / ds.foo
    >>> with dask.config.set({"awkward.optimization.enabled": False}):
diff --git a/pyproject.toml b/pyproject.toml
index faba58ec..ddd7fb2b 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -49,6 +49,7 @@ docs = [
   "dask-awkward[complete]",
   "dask-sphinx-theme >=3.0.2",
   "sphinx-design",
+  "sphinx-codeautolink",
   "requests >=2.27.1",
 ]
 test = [
diff --git a/src/dask_awkward/lib/core.py b/src/dask_awkward/lib/core.py
index f9b7d280..c0b6861f 100644
--- a/src/dask_awkward/lib/core.py
+++ b/src/dask_awkward/lib/core.py
@@ -2307,7 +2307,7 @@ def partition_compatibility(*args: Array) -> PartitionCompatibility:
     >>> import dask_awkward as dak
     >>> import awkward as ak
     >>> concrete = ak.Array([[1, 2, 3], [4], [5, 6], [0, 0, 0, 0]])
-    >>> lazy = dak.from_awkward(concrete npartitions=2)
+    >>> lazy = dak.from_awkward(concrete, npartitions=2)
     >>> selection = dak.sum(lazy, axis=1) == 0
     >>> dak.partition_compatibility(lazy, selection)
     <PartitionCompatibility.YES: 0>
diff --git a/src/dask_awkward/lib/io/text.py b/src/dask_awkward/lib/io/text.py
index 6df8265e..eb82f5eb 100644
--- a/src/dask_awkward/lib/io/text.py
+++ b/src/dask_awkward/lib/io/text.py
@@ -60,7 +60,10 @@ def from_text(
     compression: str | None = "infer",
     storage_options: dict | None = None,
 ) -> Array:
-    """Read text data as array of strings; each line an element.
+    """Create an Array collection from text data and a delimiter.
+
+    The default behavior of this input function is to create an array
+    collection where elements are seperated by newlines.
 
     Parameters
     ----------
@@ -85,7 +88,7 @@ def from_text(
     Examples
     --------
     >>> import dask_awkward as dak
-    >>> dak.from_text("s3://path/to/files/*.txt", blocksize="256 MiB")
+    >>> ds = dak.from_text("s3://path/to/files/*.txt", blocksize="256 MiB")
 
     """
     fs, token, paths = get_fs_token_paths(source, storage_options=storage_options or {})