doc/rust: deprecate cargoSha256

doc/languages-frameworks/rust.section.md

@@ -46,19 +46,24 @@ rustPlatform.buildRustPackage rec {
 }
 ```
 
-`buildRustPackage` requires either a `cargoHash` (preferred) or a
-`cargoSha256` attribute, computed over all crate sources of this package.
-`cargoHash` supports [SRI](https://www.w3.org/TR/SRI/) hashes and should be
-preferred over `cargoSha256` which was used for traditional Nix SHA-256 hashes.
-For example:
+`buildRustPackage` requires a `cargoHash` attribute, computed over all crate sources of this package.
+
+::: {.warning}
+`cargoSha256` is already deprecated, and is subject to removal in favor of
+`cargoHash` which supports [SRI](https://www.w3.org/TR/SRI/) hashes.
+
+If you are still using `cargoSha256`, you can simply replace it with
+`cargoHash` and recompute the hash, or convert the original sha256 to SRI
+hash using `nix-hash --to-sri --type sha256 "<original sha256>"`.
+:::
 
 ```nix
 {
   cargoHash = "sha256-l1vL2ZdtDRxSGvP0X/l3nMw8+6WF67KPutJEzUROjg8=";
 }
 ```
 
-Exception: If the application has cargo `git` dependencies, the `cargoHash`/`cargoSha256`
+Exception: If the application has cargo `git` dependencies, the `cargoHash`
 approach will not work, and you will need to copy the `Cargo.lock` file of the application
 to nixpkgs and continue with the next section for specifying the options of the `cargoLock`
 section.
@@ -76,14 +81,6 @@ then be taken from the failed build. A fake hash can be used for
 }
 ```
 
-For `cargoSha256` you can use:
-
-```nix
-{
-  cargoSha256 = lib.fakeSha256;
-}
-```
-
 Per the instructions in the [Cargo Book](https://doc.rust-lang.org/cargo/guide/cargo-toml-vs-cargo-lock.html)
 best practices guide, Rust applications should always commit the `Cargo.lock`
 file in git to ensure a reproducible build. However, a few packages do not, and
@@ -98,7 +95,7 @@ directory into a tar.gz archive.
 The tarball with vendored dependencies contains a directory with the
 package's `name`, which is normally composed of `pname` and
 `version`. This means that the vendored dependencies hash
-(`cargoHash`/`cargoSha256`) is dependent on the package name and
+(`cargoHash`) is dependent on the package name and
 version. The `cargoDepsName` attribute can be used to use another name
 for the directory of vendored dependencies. For example, the hash can
 be made invariant to the version by setting `cargoDepsName` to
@@ -123,7 +120,7 @@ rustPlatform.buildRustPackage rec {
 
 ### Importing a `Cargo.lock` file {#importing-a-cargo.lock-file}
 
-Using a vendored hash (`cargoHash`/`cargoSha256`) is tedious when using
+Using a vendored hash (`cargoHash`) is tedious when using
 `buildRustPackage` within a project, since it requires that the hash
 is updated after every change to `Cargo.lock`. Therefore,
 `buildRustPackage` also supports vendoring dependencies directly from