From 8d1ca7b89fed64d1dc03aad47118f342631a3cab Mon Sep 17 00:00:00 2001
From: Ivan Petkov <ivanppetkov@gmail.com>
Date: Tue, 24 Sep 2024 20:40:28 -0700
Subject: [PATCH] registryFromSparse: add missing API docs

---
 docs/API.md | 46 ++++++++++++++++++++++++++++++++++++++++++++--
 1 file changed, 44 insertions(+), 2 deletions(-)

diff --git a/docs/API.md b/docs/API.md
index 707df739..310223ac 100644
--- a/docs/API.md
+++ b/docs/API.md
@@ -60,8 +60,9 @@ newLib = craneLib.appendCrateRegistries [
 
   # Or even
   (lib.registryFromSparse {
-    url = "https://index.crates.io/";
-    sha256 = "d16740883624df970adac38c70e35cf077a2a105faa3862f8f99a65da96b14a3";
+    indexUrl = "https://index.crates.io/config.json";
+    configSha256 = "1cxgzdm1ipqmgwnq7kgym92axna7pfyhgfla63vl7dvydwn3m52v";
+    fetchurlExtraArgs = {};
   })
 ];
 ```
@@ -1382,6 +1383,47 @@ craneLib.registryFromGitIndex {
 # }
 ```
 
+### `craneLib.registryFromSparse`
+
+`registryFromSparse :: set -> set`
+
+Prepares a (sparse) crate registry into a format that can be passed directly to
+`appendCrateRegistries` using the registry's download URL.
+
+If the registry in question has a stable download URL (which either never
+changes, or it does so very infrequently), then `registryFromDownloadUrl` is a
+great and lightweight choice for including the registry. To get started,
+download the registry's `config.json` and copy the value of the `dl` entry.
+
+If the registry's download endpoint changes more frequently and you would like
+to infer the configuration directly from a git revision, consider using
+`registryFromGitIndex` as an alternative.
+
+If the registry needs a special way of accessing crate sources the
+`fetchurlExtraArgs` set can be used to influence the behavior of fetching the
+crate sources (e.g. by setting `curlOptsList`)
+
+#### Required attributes
+* `indexUrl`: an HTTP URL to the registry's config.json
+* `configSha256`: a sha256 hash of the contents of config.json
+
+#### Optional attributes
+* `fetchurlExtraArgs`: a set of arguments which will be passed on to the
+  `fetchurl` for each crate being sourced from this registry
+
+```nix
+craneLib.registryFromSparse {
+  indexUrl = "https://index.crates.io/config.json";
+  configSha256 = "1cxgzdm1ipqmgwnq7kgym92axna7pfyhgfla63vl7dvydwn3m52v";
+}
+# {
+#   "sparse+https://index.crates.io/config.json/" = {
+#     downloadUrl = "https://static.crates.io/crates/{crate}/{version}/download";
+#     fetchurlExtraArgs = { };
+#   };
+# }
+```
+
 ### `craneLib.urlForCargoPackage`
 
 `urlForCargoPackage :: set -> set`