From 8c350c2069ac3eed6344fa62e3249afa0ce2728c Mon Sep 17 00:00:00 2001 From: Emily Date: Sun, 9 Jul 2023 10:18:52 +0100 Subject: [PATCH] docs: update for Markdown migration --- docs/contributing.adoc | 4 ++-- docs/release-notes/rl-2311.adoc | 13 +++++++++++-- 2 files changed, 13 insertions(+), 4 deletions(-) diff --git a/docs/contributing.adoc b/docs/contributing.adoc index 54dc2692..3a1805f2 100644 --- a/docs/contributing.adoc +++ b/docs/contributing.adoc @@ -94,11 +94,11 @@ All contributed code _must_ pass the test suite. [[sec-guidelines-module-maintainer]] ==== Add relevant documentation +:nixpkgs-markdown: https://nixos.org/manual/nixpkgs/unstable/#sec-contributing-markup :docbook: https://tdg.docbook.org/ :asciidoc: https://asciidoc.org/ -:docbook-rocks: https://berbiche.github.io/docbook.rocks/ -Many code changes require changing the documentation as well. Module options should be documented with DocBook. See {docbook-rocks}[DocBook rocks!] for a quick introduction and {docbook}[DocBook 5: The Definitive Guide] for in-depth information of DocBook. Home Manager is itself documented using a combination of DocBook and {asciidoc}[AsciiDoc]. All text is hosted in Home Manager's Git repository. +Many code changes require changing the documentation as well. Module options should be documented with {nixpkgs-markdown}[Nixpkgs-flavoured Markdown]. Home Manager is itself documented using a combination of {docbook}[DocBook] and {asciidoc}[AsciiDoc]. All text is hosted in Home Manager's Git repository. The HTML version of the manual containing both the module option descriptions and the documentation of Home Manager can be generated and opened by typing the following in a shell within a clone of the Home Manager Git repository: diff --git a/docs/release-notes/rl-2311.adoc b/docs/release-notes/rl-2311.adoc index c546d37a..4947b809 100644 --- a/docs/release-notes/rl-2311.adoc +++ b/docs/release-notes/rl-2311.adoc @@ -5,12 +5,14 @@ This is the current unstable branch and the information in this section is there [[sec-release-23.11-highlights]] === Highlights +:babelfish: https://github.com/bouk/babelfish +:nixpkgs-markdown: https://nixos.org/manual/nixpkgs/unstable/#sec-contributing-markup This release has the following notable changes: * When using <>, the setup code for <> is now translated -with https://github.com/bouk/babelfish[babelfish]. +with {babelfish}[babelfish]. This should result in significantly faster shell startup times but could theoretically break if you have very complex bash expressions in a session variable. @@ -20,9 +22,16 @@ Please report any issues you experience. has been supplanted by `release.json`, which contains more information about the branch. If you have any external code reading this file, -please migrate to using `release.json` instead. +please switch to consuming `release.json` instead. The `.release` file will be removed in 24.05. +* Home Manager has migrated to using +the upstream Nixpkgs `lib.nixosOptionsDoc` processor +for option documentation. +If you have any external Home Manager modules, +their option descriptions and literal examples should be translated +to {nixpkgs-markdown}[Nixpkgs-flavoured Markdown]. + [[sec-release-23.11-state-version-changes]] === State Version Changes