diff --git a/maintainers/documentation-project-2023.md b/maintainers/documentation-project-2023.md index 2004835a5..81de33998 100644 --- a/maintainers/documentation-project-2023.md +++ b/maintainers/documentation-project-2023.md @@ -1,4 +1,4 @@ -# Documentation Project Proposal 2023 +# Documentation project proposal 2023 ## Offer a learning journey for Nix beginners diff --git a/maintainers/documentation-survey.md b/maintainers/documentation-survey.md index edf95e4aa..0cccf4c75 100644 --- a/maintainers/documentation-survey.md +++ b/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 diff --git a/maintainers/this-month-in-nix-docs/README.md b/maintainers/this-month-in-nix-docs/README.md index a0aa2d4d3..e8ee5d0e3 100644 --- a/maintainers/this-month-in-nix-docs/README.md +++ b/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: diff --git a/source/contributing/documentation/diataxis.md b/source/contributing/documentation/diataxis.md index aa466c7ac..8cd7d75f1 100644 --- a/source/contributing/documentation/diataxis.md +++ b/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. diff --git a/source/contributing/documentation/index.md b/source/contributing/documentation/index.md index d89d1ed86..b5d1cb86f 100644 --- a/source/contributing/documentation/index.md +++ b/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. diff --git a/source/recommended-reading.md b/source/recommended-reading.md index bb8df4551..04fd168e9 100644 --- a/source/recommended-reading.md +++ b/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) diff --git a/source/tutorials/first-steps/index.md b/source/tutorials/first-steps/index.md index 77f32e69b..68ade16f5 100644 --- a/source/tutorials/first-steps/index.md +++ b/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. diff --git a/source/tutorials/nix-language.md b/source/tutorials/nix-language.md index ae2b6fc89..762ee1e54 100644 --- a/source/tutorials/nix-language.md +++ b/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”. diff --git a/source/tutorials/nixos/continuous-integration-github-actions.md b/source/tutorials/nixos/continuous-integration-github-actions.md index e099d4f78..e04f553e3 100644 --- a/source/tutorials/nixos/continuous-integration-github-actions.md +++ b/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. diff --git a/source/tutorials/nixos/installing-nixos-on-a-raspberry-pi.md b/source/tutorials/nixos/installing-nixos-on-a-raspberry-pi.md index dc3438cb8..38eadf1be 100644 --- a/source/tutorials/nixos/installing-nixos-on-a-raspberry-pi.md +++ b/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. diff --git a/source/tutorials/packaging-existing-software.md b/source/tutorials/packaging-existing-software.md index e732a6d93..9557fc3fe 100644 --- a/source/tutorials/packaging-existing-software.md +++ b/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.