From f5dafbfa830337ea4c0d3227b27f957007342e47 Mon Sep 17 00:00:00 2001 From: Silvan Mosberger Date: Tue, 5 Dec 2023 03:33:53 +0100 Subject: [PATCH] doc: Rename to Nixpkgs reference manual and state purpose For the time being, we're moving towards https://nix.dev/ containing all tutorials and guides. The Nixpkgs manual is reinforced to be a _reference_ manual. While it's not just reference for now, that's what the docs team is working towards. This commits rewrites the Nixpkgs manual introduction to reflect that and point to some more useful links. The contribution docs are updated similarly so it's not missed. Co-authored-by: Valentin Gagarin Co-authored-by: Robert Hensing --- doc/README.md | 18 +++++++++++------- doc/manual.md.in | 2 +- doc/preface.chapter.md | 14 +++++++++----- lib/README.md | 2 +- 4 files changed, 22 insertions(+), 14 deletions(-) diff --git a/doc/README.md b/doc/README.md index 9dee2d30d730..d441a3b7204a 100644 --- a/doc/README.md +++ b/doc/README.md @@ -1,14 +1,18 @@ -# Contributing to the Nixpkgs manual +# Contributing to the Nixpkgs reference manual -This directory houses the sources files for the Nixpkgs manual. +This directory houses the sources files for the Nixpkgs reference manual. + +Going forward, it should only contain [reference](https://nix.dev/contributing/documentation/diataxis#reference) documentation. +For tutorials, guides and explanations, contribute to instead. + +For documentation only relevant for contributors, use Markdown files and code comments in the source code. + +Rendered documentation: +- [Unstable (from master)](https://nixos.org/manual/nixpkgs/unstable/) +- [Stable (from latest release)](https://nixos.org/manual/nixpkgs/stable/) -You can find the [rendered documentation for Nixpkgs `unstable` on nixos.org](https://nixos.org/manual/nixpkgs/unstable/). The rendering tool is [nixos-render-docs](../pkgs/tools/nix/nixos-render-docs/src/nixos_render_docs), sometimes abbreviated `nrd`. -[Docs for Nixpkgs stable](https://nixos.org/manual/nixpkgs/stable/) are also available. - -If you're only getting started with Nix, go to [nixos.org/learn](https://nixos.org/learn). - ## Contributing to this documentation You can quickly check your edits with `nix-build`: diff --git a/doc/manual.md.in b/doc/manual.md.in index 52971ff526c2..642247e16612 100644 --- a/doc/manual.md.in +++ b/doc/manual.md.in @@ -1,4 +1,4 @@ -# Nixpkgs Manual {#nixpkgs-manual} +# Nixpkgs Reference Manual {#nixpkgs-manual} ## Version @MANUAL_VERSION@ ```{=include=} chapters diff --git a/doc/preface.chapter.md b/doc/preface.chapter.md index aa6acca1217a..93cd1a00b4f2 100644 --- a/doc/preface.chapter.md +++ b/doc/preface.chapter.md @@ -6,11 +6,15 @@ The Nix Packages collection (Nixpkgs) is a set of thousands of packages for the Packages are available for several platforms, and can be used with the Nix package manager on most GNU/Linux distributions as well as [NixOS](https://nixos.org/nixos). -This manual primarily describes how to write packages for the Nix Packages collection -(Nixpkgs). Thus it’s mainly for packagers and developers who want to add packages to -Nixpkgs. If you like to learn more about the Nix package manager and the Nix -expression language, then you are kindly referred to the [Nix manual](https://nixos.org/nix/manual/). -The NixOS distribution is documented in the [NixOS manual](https://nixos.org/nixos/manual/). +This document is the user [_reference_](https://nix.dev/contributing/documentation/diataxis#reference) manual for Nixpkgs. +It describes entire public interface of Nixpkgs in a concise and orderly manner, and all relevant behaviors, with examples and cross-references. + +To discover other kinds of documentation: +- [nix.dev](https://nix.dev/): Tutorials and guides for getting things done with Nix +- [NixOS **Option Search**](https://search.nixos.org/options) and reference documentation +- [Nixpkgs **Package Search**](https://search.nixos.org/packages) +- [**NixOS** manual](https://nixos.org/manual/nixos/stable/): Reference documentation for the NixOS Linux distribution +- [`CONTRIBUTING.md`](https://github.com/NixOS/nixpkgs/blob/master/CONTRIBUTING.md): Contributing to Nixpkgs, including this manual ## Overview of Nixpkgs {#overview-of-nixpkgs} diff --git a/lib/README.md b/lib/README.md index 220940bc2122..a886cf5bfb55 100644 --- a/lib/README.md +++ b/lib/README.md @@ -42,7 +42,7 @@ Reference documentation for library functions is written above each function as These comments are processed using [nixdoc](https://github.com/nix-community/nixdoc) and [rendered in the Nixpkgs manual](https://nixos.org/manual/nixpkgs/stable/#chap-functions). The nixdoc README describes the [comment format](https://github.com/nix-community/nixdoc#comment-format). -See the [chapter on contributing to the Nixpkgs manual](https://nixos.org/manual/nixpkgs/#chap-contributing) for how to build the manual. +See [doc/README.md](../doc/README.md) for how to build the manual. ## Running tests