mirror of
https://github.com/NixOS/nix.dev.git
synced 2024-10-18 14:32:43 -04:00
Merge pull request #798 from NixOS/vale
Add prose lint checks with Vale
This commit is contained in:
commit
d135cab53f
13
.github/workflows/vale.yml
vendored
Normal file
13
.github/workflows/vale.yml
vendored
Normal file
|
@ -0,0 +1,13 @@
|
||||||
|
name: Prose lint checks
|
||||||
|
on:
|
||||||
|
pull_request:
|
||||||
|
push:
|
||||||
|
|
||||||
|
jobs:
|
||||||
|
vale:
|
||||||
|
runs-on: ubuntu-latest
|
||||||
|
steps:
|
||||||
|
- uses: actions/checkout@v4
|
||||||
|
- uses: cachix/install-nix-action@v23
|
||||||
|
- name: Vale
|
||||||
|
run: nix-shell --run "vale maintainers source"
|
1
.gitignore
vendored
1
.gitignore
vendored
|
@ -1,5 +1,4 @@
|
||||||
.direnv/
|
.direnv/
|
||||||
.envrc
|
|
||||||
build/
|
build/
|
||||||
extracted/
|
extracted/
|
||||||
requirements_frozen.txt
|
requirements_frozen.txt
|
||||||
|
|
7
.vale.ini
Normal file
7
.vale.ini
Normal file
|
@ -0,0 +1,7 @@
|
||||||
|
# https://vale.sh/docs/topics/config
|
||||||
|
MinAlertLevel = suggestion
|
||||||
|
StylesPath = vale
|
||||||
|
Vocab = Nix
|
||||||
|
|
||||||
|
[*.md]
|
||||||
|
BasedOnStyles = Style
|
|
@ -66,9 +66,10 @@ in
|
||||||
|
|
||||||
shell = pkgs.mkShell {
|
shell = pkgs.mkShell {
|
||||||
inputsFrom = [ nix-dev ];
|
inputsFrom = [ nix-dev ];
|
||||||
packages = with pkgs.python310.pkgs; [
|
packages = [
|
||||||
black
|
|
||||||
devmode
|
devmode
|
||||||
|
pkgs.python310.pkgs.black
|
||||||
|
pkgs.vale
|
||||||
];
|
];
|
||||||
};
|
};
|
||||||
}
|
}
|
||||||
|
|
|
@ -1,4 +1,4 @@
|
||||||
# Documentation Project Proposal 2023
|
# Documentation project proposal 2023
|
||||||
|
|
||||||
## Offer a learning journey for Nix beginners
|
## Offer a learning journey for Nix beginners
|
||||||
|
|
||||||
|
|
|
@ -100,7 +100,7 @@ To better navigate the material and judge its relevance, every entry should prov
|
||||||
|
|
||||||
- https://www.youtube.com/watch?v=jf0nIn2oS8A&list=PL-saUBvIJzOkjAw_vOac75v-x6EzNzZq-&index=4
|
- https://www.youtube.com/watch?v=jf0nIn2oS8A&list=PL-saUBvIJzOkjAw_vOac75v-x6EzNzZq-&index=4
|
||||||
|
|
||||||
## How-To Guides
|
## How-to guides
|
||||||
|
|
||||||
### Nix
|
### Nix
|
||||||
|
|
||||||
|
|
|
@ -1,4 +1,4 @@
|
||||||
# This Month in Nix Docs
|
# This month in Nix docs
|
||||||
This is a script and template for compiling "This Month in Nix Docs". The process is semi-automated. The script queries a collection of Nix repositories, looking for merged PRs with documentation-related labels, RFCs (you have to look through these manually), and tracking issues in this repository.
|
This is a script and template for compiling "This Month in Nix Docs". The process is semi-automated. The script queries a collection of Nix repositories, looking for merged PRs with documentation-related labels, RFCs (you have to look through these manually), and tracking issues in this repository.
|
||||||
|
|
||||||
A new post is created via:
|
A new post is created via:
|
||||||
|
|
|
@ -39,7 +39,7 @@ A concept can also describe the historical context behind why something works th
|
||||||
|
|
||||||
If you find yourself wanting to write about the nitty gritty details of how something works, you most likely want to write an explanation.
|
If you find yourself wanting to write about the nitty gritty details of how something works, you most likely want to write an explanation.
|
||||||
|
|
||||||
### Guides vs. Tutorials
|
### Guides vs. tutorials
|
||||||
|
|
||||||
We find that contributors primarily struggle with the difference between a Guide and a Tutorial.
|
We find that contributors primarily struggle with the difference between a Guide and a Tutorial.
|
||||||
|
|
||||||
|
|
|
@ -1,4 +1,4 @@
|
||||||
# Contributing Documentation
|
# Contributing documentation
|
||||||
|
|
||||||
This is an overview of documentation resources for Nix, Nixpkgs, and NixOS, with suggestions how you can help to improve them.
|
This is an overview of documentation resources for Nix, Nixpkgs, and NixOS, with suggestions how you can help to improve them.
|
||||||
Documentation contributions should follow the [style guide](./style-guide.md).
|
Documentation contributions should follow the [style guide](./style-guide.md).
|
||||||
|
@ -125,7 +125,7 @@ You can help by
|
||||||
|
|
||||||
[Documentation category]: https://discourse.nixos.org/c/dev/documentation/25
|
[Documentation category]: https://discourse.nixos.org/c/dev/documentation/25
|
||||||
|
|
||||||
### Meetings and Events
|
### Meetings and events
|
||||||
|
|
||||||
Check the [Discourse community calendar] for real-time events.
|
Check the [Discourse community calendar] for real-time events.
|
||||||
|
|
||||||
|
|
|
@ -22,7 +22,7 @@
|
||||||
|
|
||||||
Introduction to writing derivations.
|
Introduction to writing derivations.
|
||||||
|
|
||||||
## Other Articles
|
## Other articles
|
||||||
|
|
||||||
- [NixOS and Flakes - An unofficial book for beginners](https://nixos-and-flakes.thiscute.world) (2023)
|
- [NixOS and Flakes - An unofficial book for beginners](https://nixos-and-flakes.thiscute.world) (2023)
|
||||||
|
|
||||||
|
|
|
@ -1,6 +1,6 @@
|
||||||
(first-steps)=
|
(first-steps)=
|
||||||
|
|
||||||
# First Steps
|
# First steps
|
||||||
|
|
||||||
This tutorial series is where you should start learning Nix.
|
This tutorial series is where you should start learning Nix.
|
||||||
|
|
||||||
|
|
|
@ -758,7 +758,7 @@ The new inner scope now contains `x` and `y`, which are used in the list `[ x y
|
||||||
:::
|
:::
|
||||||
|
|
||||||
(string-interpolation)=
|
(string-interpolation)=
|
||||||
### String Interpolation `${ ... }`
|
### String interpolation `${ ... }`
|
||||||
|
|
||||||
Previously known as “antiquotation”.
|
Previously known as “antiquotation”.
|
||||||
|
|
||||||
|
|
|
@ -7,7 +7,7 @@ myst:
|
||||||
|
|
||||||
(github-actions)=
|
(github-actions)=
|
||||||
|
|
||||||
# Continuous Integration with GitHub Actions
|
# Continuous integration with GitHub Actions
|
||||||
|
|
||||||
In this tutorial, we'll show you **a few short steps** to get started using [GitHub Actions](https://github.com/features/actions) as your continuous integration (CI) workflow for commits and pull requests.
|
In this tutorial, we'll show you **a few short steps** to get started using [GitHub Actions](https://github.com/features/actions) as your continuous integration (CI) workflow for commits and pull requests.
|
||||||
|
|
||||||
|
@ -72,7 +72,7 @@ jobs:
|
||||||
Once you commit and push to your GitHub repository,
|
Once you commit and push to your GitHub repository,
|
||||||
you should see status checks appearing on commits and PRs.
|
you should see status checks appearing on commits and PRs.
|
||||||
|
|
||||||
## Caching builds using GitHub's Cache Service
|
## Caching builds using GitHub Actions Cache
|
||||||
|
|
||||||
A quick and easy way to speed up CI on any GitHub repository is to use the [Magic Nix Cache][magic-nix-cache].
|
A quick and easy way to speed up CI on any GitHub repository is to use the [Magic Nix Cache][magic-nix-cache].
|
||||||
The Magic Nix Cache doesn't require any configuration, secrets, or credentials.
|
The Magic Nix Cache doesn't require any configuration, secrets, or credentials.
|
||||||
|
|
|
@ -92,7 +92,7 @@ To benefit from updates and bug fixes from the vendor, we'll start by updating R
|
||||||
# BOOTFS=/mnt FIRMWARE_RELEASE_STATUS=stable rpi-eeprom-update -d -a
|
# BOOTFS=/mnt FIRMWARE_RELEASE_STATUS=stable rpi-eeprom-update -d -a
|
||||||
```
|
```
|
||||||
|
|
||||||
## Installing and Configuring NixOS
|
## Installing and configuring NixOS
|
||||||
|
|
||||||
Now we'll install NixOS with our own configuration, here creating a `guest` user and enabling the SSH daemon.
|
Now we'll install NixOS with our own configuration, here creating a `guest` user and enabling the SSH daemon.
|
||||||
|
|
||||||
|
|
|
@ -6,7 +6,7 @@ myst:
|
||||||
---
|
---
|
||||||
|
|
||||||
(packaging-existing-software)=
|
(packaging-existing-software)=
|
||||||
# Packaging Existing Software With Nix
|
# Packaging existing software with Nix
|
||||||
|
|
||||||
One of Nix's primary use-cases is in addressing common difficulties encountered while packaging software, like managing dependencies.
|
One of Nix's primary use-cases is in addressing common difficulties encountered while packaging software, like managing dependencies.
|
||||||
|
|
||||||
|
@ -27,7 +27,7 @@ Packages have mostly standardised attributes and output layouts, allowing them t
|
||||||
For the purposes of this tutorial, "package" means something like "result of a derivation"; this is the artifact you or others will use, as a consequence of having "packaged existing software with Nix".
|
For the purposes of this tutorial, "package" means something like "result of a derivation"; this is the artifact you or others will use, as a consequence of having "packaged existing software with Nix".
|
||||||
:::
|
:::
|
||||||
|
|
||||||
## A Simple Project
|
## A simple project
|
||||||
To start, consider this skeleton derivation:
|
To start, consider this skeleton derivation:
|
||||||
|
|
||||||
```nix
|
```nix
|
||||||
|
@ -97,7 +97,7 @@ error: cannot evaluate a function that has an argument without a value ('lib')
|
||||||
|
|
||||||
Problem: the expression in `hello.nix` is a *function*, which only produces its intended output if it is passed the correct *arguments*.
|
Problem: the expression in `hello.nix` is a *function*, which only produces its intended output if it is passed the correct *arguments*.
|
||||||
|
|
||||||
### A New Command
|
### A new command
|
||||||
`lib` is available from `nixpkgs`, which must be imported with another Nix expression in order to pass it as an argument to this derivation.
|
`lib` is available from `nixpkgs`, which must be imported with another Nix expression in order to pass it as an argument to this derivation.
|
||||||
|
|
||||||
The recommended way to do this is to create a `default.nix` in the same directory as `hello.nix`, with the following contents:
|
The recommended way to do this is to create a `default.nix` in the same directory as `hello.nix`, with the following contents:
|
||||||
|
@ -140,7 +140,7 @@ error:
|
||||||
got: sha256:0xw6cr5jgi1ir13q6apvrivwmmpr5j8vbymp0x6ll0kcv6366hnn
|
got: sha256:0xw6cr5jgi1ir13q6apvrivwmmpr5j8vbymp0x6ll0kcv6366hnn
|
||||||
```
|
```
|
||||||
|
|
||||||
### Finding The File Hash
|
### Finding the file hash
|
||||||
As expected, the incorrect file hash caused an error, and Nix helpfully provided the correct one, which you can now substitute into `hello.nix` to replace `lib.fakeSha256`:
|
As expected, the incorrect file hash caused an error, and Nix helpfully provided the correct one, which you can now substitute into `hello.nix` to replace `lib.fakeSha256`:
|
||||||
|
|
||||||
```nix
|
```nix
|
||||||
|
@ -181,7 +181,7 @@ Great news: the derivation built successfully!
|
||||||
The console output shows that `configure` was called, which produced a `Makefile` that was then used to build the project.
|
The console output shows that `configure` was called, which produced a `Makefile` that was then used to build the project.
|
||||||
It wasn't necessary to write any build instructions in this case because the `stdenv` build system is based on `autoconf`, which automatically detected the structure of the project directory.
|
It wasn't necessary to write any build instructions in this case because the `stdenv` build system is based on `autoconf`, which automatically detected the structure of the project directory.
|
||||||
|
|
||||||
### Build Result
|
### Build result
|
||||||
Check your working directory for the result:
|
Check your working directory for the result:
|
||||||
|
|
||||||
```console
|
```console
|
||||||
|
@ -200,7 +200,7 @@ Congratulations, you have successfully packaged your first program with Nix!
|
||||||
|
|
||||||
Next, you'll package another piece of software with external-to-`stdenv` dependencies that present new challenges, requiring you to make use of more `mkDerivation` features.
|
Next, you'll package another piece of software with external-to-`stdenv` dependencies that present new challenges, requiring you to make use of more `mkDerivation` features.
|
||||||
|
|
||||||
## Something Bigger
|
## Something bigger
|
||||||
Now you will package a somewhat more complicated program, [`icat`](https://github.com/atextor/icat), which allows you to render images in your terminal.
|
Now you will package a somewhat more complicated program, [`icat`](https://github.com/atextor/icat), which allows you to render images in your terminal.
|
||||||
|
|
||||||
To start, modify the `default.nix` from the previous section by adding a new attribute for `icat`:
|
To start, modify the `default.nix` from the previous section by adding a new attribute for `icat`:
|
||||||
|
@ -253,7 +253,7 @@ stdenv.mkDerivation {
|
||||||
}
|
}
|
||||||
```
|
```
|
||||||
|
|
||||||
### Fetching Source from GitHub
|
### Fetching source from GitHub
|
||||||
While `fetchzip` required `url` and `sha256` arguments, more are needed for [`fetchFromGitHub`](https://nixos.org/manual/nixpkgs/stable/#fetchfromgithub).
|
While `fetchzip` required `url` and `sha256` arguments, more are needed for [`fetchFromGitHub`](https://nixos.org/manual/nixpkgs/stable/#fetchfromgithub).
|
||||||
|
|
||||||
The source is hosted on GitHub at `https://github.com/atextor/icat`, which already gives the first two arguments:
|
The source is hosted on GitHub at `https://github.com/atextor/icat`, which already gives the first two arguments:
|
||||||
|
@ -297,7 +297,7 @@ stdenv.mkDerivation {
|
||||||
}
|
}
|
||||||
```
|
```
|
||||||
|
|
||||||
### Missing Dependencies
|
### Missing dependencies
|
||||||
Running `nix-build` with the new `icat` attribute, an entirely new issue is reported:
|
Running `nix-build` with the new `icat` attribute, an entirely new issue is reported:
|
||||||
|
|
||||||
```console
|
```console
|
||||||
|
@ -437,7 +437,7 @@ error: builder for '/nix/store/x1d79ld8jxqdla5zw2b47d2sl87mf56k-icat.drv' failed
|
||||||
|
|
||||||
The missing dependency error is solved, but there is now another problem: `make: *** No rule to make target 'install'. Stop.`
|
The missing dependency error is solved, but there is now another problem: `make: *** No rule to make target 'install'. Stop.`
|
||||||
|
|
||||||
### installPhase
|
### `installPhase`
|
||||||
The `stdenv` is automatically working with the `Makefile` that comes with `icat`: you can see in the console output that `configure` and `make` are executed without issue, so the `icat` binary is compiling successfully.
|
The `stdenv` is automatically working with the `Makefile` that comes with `icat`: you can see in the console output that `configure` and `make` are executed without issue, so the `icat` binary is compiling successfully.
|
||||||
|
|
||||||
The failure occurs when the `stdenv` attempts to run `make install`: the `Makefile` included in the project happens to lack an `install` target, and the `README` in the `icat` repository only mentions using `make` to build the tool, leaving the installation step up to users.
|
The failure occurs when the `stdenv` attempts to run `make install`: the `Makefile` included in the project happens to lack an `install` target, and the `README` in the `icat` repository only mentions using `make` to build the tool, leaving the installation step up to users.
|
||||||
|
@ -477,7 +477,7 @@ stdenv.mkDerivation {
|
||||||
}
|
}
|
||||||
```
|
```
|
||||||
|
|
||||||
### Phases and Hooks
|
### Phases and hooks
|
||||||
Nixpkgs `stdenv.mkDerivation` derivations are separated into [phases](https://nixos.org/manual/nixpkgs/stable/#sec-stdenv-phases), each of which is intended to control some aspect of the build process.
|
Nixpkgs `stdenv.mkDerivation` derivations are separated into [phases](https://nixos.org/manual/nixpkgs/stable/#sec-stdenv-phases), each of which is intended to control some aspect of the build process.
|
||||||
|
|
||||||
You saw earlier how `stdenv.mkDerivation` expected the project's `Makefile` to have an `install` target, and failed when it didn't.
|
You saw earlier how `stdenv.mkDerivation` expected the project's `Makefile` to have an `install` target, and failed when it didn't.
|
||||||
|
|
9
vale/Style/headers.yml
Normal file
9
vale/Style/headers.yml
Normal file
|
@ -0,0 +1,9 @@
|
||||||
|
extends: capitalization
|
||||||
|
message: "'%s' should be in sentence case"
|
||||||
|
level: error
|
||||||
|
scope: heading
|
||||||
|
# $title, $sentence, $lower, $upper, or a pattern.
|
||||||
|
match: $sentence
|
||||||
|
indicators:
|
||||||
|
# For headers like `1. Foo`
|
||||||
|
- "."
|
19
vale/Vocab/Nix/accept.txt
Normal file
19
vale/Vocab/Nix/accept.txt
Normal file
|
@ -0,0 +1,19 @@
|
||||||
|
Cachix
|
||||||
|
Docker
|
||||||
|
Dolstra
|
||||||
|
Eelco
|
||||||
|
Frequently Asked Questions
|
||||||
|
GitHub
|
||||||
|
GitHub Actions
|
||||||
|
GitHub Actions Cache
|
||||||
|
Hello(,)? World(!)?
|
||||||
|
Nix
|
||||||
|
Nix Pills
|
||||||
|
NixOS
|
||||||
|
Nixpkgs
|
||||||
|
Raspberry Pi
|
||||||
|
Terraform
|
||||||
|
Tweag
|
||||||
|
URL(s)?
|
||||||
|
nix.dev
|
||||||
|
nixos.org
|
Loading…
Reference in a new issue