Merge pull request #798 from NixOS/vale

Add prose lint checks with Vale

.envrc

@@ -0,0 +1 @@
+use nix

.github/workflows/vale.yml

@@ -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"

.gitignore

@@ -1,5 +1,4 @@
 .direnv/
-.envrc
 build/
 extracted/
 requirements_frozen.txt

.vale.ini

@@ -0,0 +1,7 @@
+# https://vale.sh/docs/topics/config
+MinAlertLevel = suggestion
+StylesPath = vale
+Vocab = Nix
+
+[*.md]
+BasedOnStyles = Style

default.nix

@@ -66,9 +66,10 @@ in
 
   shell = pkgs.mkShell {
     inputsFrom = [ nix-dev ];
-    packages = with pkgs.python310.pkgs; [
-      black
+    packages = [
       devmode
+      pkgs.python310.pkgs.black
+      pkgs.vale
     ];
   };
 }

maintainers/documentation-project-2023.md

@@ -1,4 +1,4 @@
-# Documentation Project Proposal 2023
+# Documentation project proposal 2023
 
 ## Offer a learning journey for Nix beginners
 

maintainers/documentation-survey.md

@@ -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
 
-## How-To Guides
+## How-to guides
 
 ### Nix
 

maintainers/this-month-in-nix-docs/README.md

@@ -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.
 
 A new post is created via:

source/contributing/documentation/diataxis.md

@@ -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.
 
-### Guides vs. Tutorials
+### Guides vs. tutorials
 
 We find that contributors primarily struggle with the difference between a Guide and a Tutorial.
 

source/contributing/documentation/index.md

@@ -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.
 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
 
-### Meetings and Events
+### Meetings and events
 
 Check the [Discourse community calendar] for real-time events.
 

source/recommended-reading.md

@@ -22,7 +22,7 @@
 
   Introduction to writing derivations.
 
-## Other Articles
+## Other articles
 
 - [NixOS and Flakes - An unofficial book for beginners](https://nixos-and-flakes.thiscute.world) (2023)
 

source/tutorials/first-steps/index.md

@@ -1,6 +1,6 @@
 (first-steps)=
 
-# First Steps
+# First steps
 
 This tutorial series is where you should start learning Nix.
 

source/tutorials/nix-language.md

@@ -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 `${ ... }`
 
 Previously known as “antiquotation”.
 

source/tutorials/nixos/continuous-integration-github-actions.md

@@ -7,7 +7,7 @@ myst:
 
 (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.
 
@@ -72,7 +72,7 @@ jobs:
 Once you commit and push to your GitHub repository,
 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].
 The Magic Nix Cache doesn't require any configuration, secrets, or credentials.

source/tutorials/nixos/installing-nixos-on-a-raspberry-pi.md

@@ -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
 ```
 
-## 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.
 

source/tutorials/packaging-existing-software.md

@@ -6,7 +6,7 @@ myst:
 ---
 
 (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.
 
@@ -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".
 :::
 
-## A Simple Project
+## A simple project
 To start, consider this skeleton derivation:
 
 ```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*.
 
-### 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.
 
 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
 ```
 
-### 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`:
 
 ```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.
 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:
 
 ```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.
 
-## 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.
 
 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).
 
 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:
 
 ```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.`
 
-### 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 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.
 
 You saw earlier how `stdenv.mkDerivation` expected the project's `Makefile` to have an `install` target, and failed when it didn't.

vale/Style/headers.yml

@@ -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`
+  - "."

vale/Vocab/Nix/accept.txt

@@ -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