doc/../rust.section.md: fix incorrect header depths · Pull Request #187919 · NixOS/nixpkgs

ghost · 2022-08-22T21:30:19Z

Description of changes

The headings for the Rust section are structured incorrectly in two ways:

The section "Compiling non-Rust packages that include Rust code" is totally specific to buildRustPackage. It should be a child of the "Compiling Rust applications with Cargo" section.
The section "Setting up nix-shell" is totally specific to buildRustCrate. It should be a child of the "Compiling Rust crates using Nix instead of Cargo" section.

Resulting header outline

# Rust

## `buildRustPackage`: Compiling Rust applications with Cargo
### Importing a `Cargo.lock` file
### Cargo features
### Cross compilation
### Running package tests
#### Tests relying on the structure of the `target/` directory
#### Disabling package-tests
#### Using `cargo-nextest`
#### Setting `test-threads`
### Building a package in `debug` mode
### Custom `build`/`install`-procedures
### Building a crate with an absent or out-of-date Cargo.lock file
### Compiling non-Rust packages that include Rust code
#### Vendoring of dependencies
#### Hooks
#### Examples
#### Python package using `setuptools-rust`
#### Python package using `maturin`

## `buildRustCrate`: Compiling Rust crates using Nix instead of Cargo
### Handling external dependencies
### Options and phases configuration
### Features
### Setting Up `nix-shell`

## Using community maintained Rust toolchains
### Using Rust nightly with `nix-shell`
### Using Rust nightly in a derivation with `buildRustPackage`

Things done

Fits CONTRIBUTING.md.

ghost · 2023-01-02T02:32:42Z

Resolved merge conflict.

ghost · 2023-03-10T06:24:44Z

Rebased.

doc/languages-frameworks/rust.section.md

figsoda · 2023-03-11T14:53:07Z

I'm still a bit unsure about this change

There is no "Compiling Rust crates using Nix instead of Cargo", and now all sections are under buildRustPackage
IMO it makes sense for "Compiling non-Rust packages that include Rust code" to be in its own section, as it is not part of buildRustPackage
Despite mentioning buildRustCrate, "Setting up nix-shell" doesn't seem to be specific to buildRustCrate, and should
Same for "Using community maintained Rust toolchains", it probably shouldn't be part of buildRustPackage or buildRustCrate sections

…tion.md This reverts the part of commit 82fe76d that affected doc/languages-frameworks/rust.section.md

The headings for the Rust section are structured incorrectly in two ways: 1. The section "Compiling non-Rust packages that include Rust code" is totally specific to `buildRustPackage`. It should be a child of the "Compiling Rust applications with Cargo" section. 1. The section "Setting up `nix-shell`" is totally specific to `buildRustCrate`. It should be a child of the "Compiling Rust crates using Nix instead of Cargo" section. - Rust - Compiling Rust applications with Cargo - ... - Compiling non-Rust packages that include Rust code - ... - Compiling Rust crates using Nix instead of Cargo - ... - Setting Up `nix-shell` - ... - Rust - Compiling Rust applications with Cargo - ... - Compiling non-Rust packages that include Rust code - ... - Compiling Rust crates using Nix instead of Cargo - ... - Setting Up `nix-shell` - ...

ghost · 2023-03-16T02:43:24Z

Yeah, #202394 deleted the documentation section for buildRustCrate. I need to rewrite this PR now.

ghost · 2023-03-16T02:50:22Z

(moved to topmost comment)

doc/languages-frameworks/rust.section.md

Co-authored-by: Jörg Thalheim <Mic92@users.noreply.github.com>

ghost · 2023-03-17T19:20:30Z

I've simply deleted the section which tried to replicate the crate2nix documentation.

crate2nix exists outside of nixpkgs, so we shouldn't try to replicate its documentation; we should link to it.

buildRustCrate is part of nixpkgs, so that's what we should document.

ghost · 2023-03-17T19:21:37Z

Note: this PR was just supposed to fix the header depths. I feel like this PR has been dragged into dealing with the whole carnix/crate2nix thing solely because of the merge conflict created by #202394

github-actions bot added 6.topic: rust General-purpose programming language emphasizing performance, type safety, and concurrency. 8.has: documentation This PR adds or changes documentation labels Aug 22, 2022

This was referenced Aug 22, 2022

doc/../rust.section.md: add section overview #187922

Closed

doc/../rust.section.md: prominently mention buildRustXX names #187921

Merged

ghost marked this pull request as ready for review August 22, 2022 21:39

ghost requested a review from zowoq as a code owner August 22, 2022 21:39

ofborg bot added 10.rebuild-darwin: 0 This PR does not cause any packages to rebuild on Darwin. 10.rebuild-linux: 0 This PR does not cause any packages to rebuild on Linux. labels Aug 22, 2022

ghost requested review from figsoda and winterqt as code owners March 10, 2023 06:24

figsoda reviewed Mar 10, 2023

View reviewed changes