nixos-render-docs: add support for examples

nixos/doc/manual/development/freeform-modules.section.md

@@ -13,7 +13,7 @@ checking for entire option trees, it is only recommended for use in
 submodules.
 
 ::: {#ex-freeform-module .example}
-**Example: Freeform submodule**
+### Freeform submodule
 
 The following shows a submodule assigning a freeform type that allows
 arbitrary attributes with `str` values below `settings`, but also

nixos/doc/manual/development/option-declarations.section.md

@@ -77,6 +77,7 @@ The option's description is "Whether to enable \<name\>.".
 For example:
 
 ::: {#ex-options-declarations-util-mkEnableOption-magic .example}
+### `mkEnableOption` usage
 ```nix
 lib.mkEnableOption (lib.mdDoc "magic")
 # is like
@@ -126,6 +127,7 @@ During the transition to CommonMark documentation `mkPackageOption` creates an o
 Examples:
 
 ::: {#ex-options-declarations-util-mkPackageOption-hello .example}
+### Simple `mkPackageOption` usage
 ```nix
 lib.mkPackageOptionMD pkgs "hello" { }
 # is like
@@ -139,6 +141,7 @@ lib.mkOption {
 :::
 
 ::: {#ex-options-declarations-util-mkPackageOption-ghc .example}
+### `mkPackageOption` with explicit default and example
 ```nix
 lib.mkPackageOptionMD pkgs "GHC" {
   default = [ "ghc" ];
@@ -156,6 +159,7 @@ lib.mkOption {
 :::
 
 ::: {#ex-options-declarations-util-mkPackageOption-extraDescription .example}
+### `mkPackageOption` with additional description text
 ```nix
 mkPackageOption pkgs [ "python39Packages" "pytorch" ] {
   extraDescription = "This is an example and doesn't actually do anything.";
@@ -217,7 +221,7 @@ changing the main service module file and the type system automatically
 enforces that there can only be a single display manager enabled.
 
 ::: {#ex-option-declaration-eot-service .example}
-**Example: Extensible type placeholder in the service module**
+### Extensible type placeholder in the service module
 ```nix
 services.xserver.displayManager.enable = mkOption {
   description = "Display manager to use";
@@ -227,7 +231,7 @@ services.xserver.displayManager.enable = mkOption {
 :::
 
 ::: {#ex-option-declaration-eot-backend-gdm .example}
-**Example: Extending `services.xserver.displayManager.enable` in the `gdm` module**
+### Extending `services.xserver.displayManager.enable` in the `gdm` module
 ```nix
 services.xserver.displayManager.enable = mkOption {
   type = with types; nullOr (enum [ "gdm" ]);
@@ -236,7 +240,7 @@ services.xserver.displayManager.enable = mkOption {
 :::
 
 ::: {#ex-option-declaration-eot-backend-sddm .example}
-**Example: Extending `services.xserver.displayManager.enable` in the `sddm` module**
+### Extending `services.xserver.displayManager.enable` in the `sddm` module
 ```nix
 services.xserver.displayManager.enable = mkOption {
   type = with types; nullOr (enum [ "sddm" ]);

nixos/doc/manual/development/option-types.section.md

@@ -36,7 +36,7 @@ merging is handled.
     together. This type is recommended when the option type is unknown.
 
     ::: {#ex-types-anything .example}
-    **Example: `types.anything` Example**
+    ### `types.anything`
 
     Two definitions of this type like
 
@@ -356,7 +356,7 @@ you will still need to provide a default value (e.g. an empty attribute set)
 if you want to allow users to leave it undefined.
 
 ::: {#ex-submodule-direct .example}
-**Example: Directly defined submodule**
+### Directly defined submodule
 ```nix
 options.mod = mkOption {
   description = "submodule example";
@@ -375,7 +375,7 @@ options.mod = mkOption {
 :::
 
 ::: {#ex-submodule-reference .example}
-**Example: Submodule defined as a reference**
+### Submodule defined as a reference
 ```nix
 let
   modOptions = {
@@ -403,7 +403,7 @@ multiple definitions of the submodule option set
 ([Example: Definition of a list of submodules](#ex-submodule-listof-definition)).
 
 ::: {#ex-submodule-listof-declaration .example}
-**Example: Declaration of a list of submodules**
+### Declaration of a list of submodules
 ```nix
 options.mod = mkOption {
   description = "submodule example";
@@ -422,7 +422,7 @@ options.mod = mkOption {
 :::
 
 ::: {#ex-submodule-listof-definition .example}
-**Example: Definition of a list of submodules**
+### Definition of a list of submodules
 ```nix
 config.mod = [
   { foo = 1; bar = "one"; }
@@ -437,7 +437,7 @@ multiple named definitions of the submodule option set
 ([Example: Definition of attribute sets of submodules](#ex-submodule-attrsof-definition)).
 
 ::: {#ex-submodule-attrsof-declaration .example}
-**Example: Declaration of attribute sets of submodules**
+### Declaration of attribute sets of submodules
 ```nix
 options.mod = mkOption {
   description = "submodule example";
@@ -456,7 +456,7 @@ options.mod = mkOption {
 :::
 
 ::: {#ex-submodule-attrsof-definition .example}
-**Example: Definition of attribute sets of submodules**
+### Definition of attribute sets of submodules
 ```nix
 config.mod.one = { foo = 1; bar = "one"; };
 config.mod.two = { foo = 2; bar = "two"; };
@@ -476,7 +476,7 @@ Types are mainly characterized by their `check` and `merge` functions.
     ([Example: Overriding a type check](#ex-extending-type-check-2)).
 
     ::: {#ex-extending-type-check-1 .example}
-    **Example: Adding a type check**
+    ### Adding a type check
 
     ```nix
     byte = mkOption {
@@ -487,7 +487,7 @@ Types are mainly characterized by their `check` and `merge` functions.
     :::
 
     ::: {#ex-extending-type-check-2 .example}
-    **Example: Overriding a type check**
+    ### Overriding a type check
 
     ```nix
     nixThings = mkOption {

nixos/doc/manual/development/settings-options.section.md

@@ -143,7 +143,7 @@ These functions all return an attribute set with these values:
     :::
 
 ::: {#ex-settings-nix-representable .example}
-**Example: Module with conventional `settings` option**
+### Module with conventional `settings` option
 
 The following shows a module for an example program that uses a JSON
 configuration file. It demonstrates how above values can be used, along
@@ -218,7 +218,7 @@ the port, which will enforce it to be a valid integer and make it show
 up in the manual.
 
 ::: {#ex-settings-typed-attrs .example}
-**Example: Declaring a type-checked `settings` attribute**
+### Declaring a type-checked `settings` attribute
 ```nix
 settings = lib.mkOption {
   type = lib.types.submodule {

nixos/doc/manual/development/writing-modules.chapter.md

@@ -37,7 +37,7 @@ options, but does not declare any. The structure of full NixOS modules
 is shown in [Example: Structure of NixOS Modules](#ex-module-syntax).
 
 ::: {#ex-module-syntax .example}
-**Example: Structure of NixOS Modules**
+### Structure of NixOS Modules
 ```nix
 { config, pkgs, ... }:
 
@@ -100,7 +100,7 @@ Exec directives](#exec-escaping-example) for an example. When using these
 functions system environment substitution should *not* be disabled explicitly.
 
 ::: {#locate-example .example}
-**Example: NixOS Module for the "locate" Service**
+### NixOS Module for the "locate" Service
 ```nix
 { config, lib, pkgs, ... }:
 
@@ -161,7 +161,7 @@ in {
 :::
 
 ::: {#exec-escaping-example .example}
-**Example: Escaping in Exec directives**
+### Escaping in Exec directives
 ```nix
 { config, lib, pkgs, utils, ... }:
 

nixos/doc/manual/installation/installing.chapter.md

@@ -538,7 +538,7 @@ drive (here `/dev/sda`). [Example: NixOS Configuration](#ex-config) shows a
 corresponding configuration Nix expression.
 
 ::: {#ex-partition-scheme-MBR .example}
-**Example: Example partition schemes for NixOS on `/dev/sda` (MBR)**
+### Example partition schemes for NixOS on `/dev/sda` (MBR)
 ```ShellSession
 # parted /dev/sda -- mklabel msdos
 # parted /dev/sda -- mkpart primary 1MB -8GB
@@ -547,7 +547,7 @@ corresponding configuration Nix expression.
 :::
 
 ::: {#ex-partition-scheme-UEFI .example}
-**Example: Example partition schemes for NixOS on `/dev/sda` (UEFI)**
+### Example partition schemes for NixOS on `/dev/sda` (UEFI)
 ```ShellSession
 # parted /dev/sda -- mklabel gpt
 # parted /dev/sda -- mkpart primary 512MB -8GB
@@ -558,7 +558,7 @@ corresponding configuration Nix expression.
 :::
 
 ::: {#ex-install-sequence .example}
-**Example: Commands for Installing NixOS on `/dev/sda`**
+### Commands for Installing NixOS on `/dev/sda`
 
 With a partitioned disk.
 
@@ -578,7 +578,7 @@ With a partitioned disk.
 :::
 
 ::: {#ex-config .example}
-**Example: NixOS Configuration**
+### Example: NixOS Configuration
 ```ShellSession
 { config, pkgs, ... }: {
   imports = [

nixos/modules/services/editors/emacs.md

@@ -80,7 +80,8 @@ The first step to declare the list of packages you want in your Emacs
 installation is to create a dedicated derivation. This can be done in a
 dedicated {file}`emacs.nix` file such as:
 
-[]{#ex-emacsNix}
+::: {.example #ex-emacsNix}
+### Nix expression to build Emacs with packages (`emacs.nix`)
 
 ```nix
 /*
@@ -136,6 +137,7 @@ in
     pkgs.notmuch   # From main packages set
   ])
 ```
+:::
 
 The result of this configuration will be an {command}`emacs`
 command which launches Emacs with all of your chosen packages in the
@@ -158,19 +160,24 @@ and yasnippet.
 
 The list of available packages in the various ELPA repositories can be seen
 with the following commands:
-[]{#module-services-emacs-querying-packages}
+::: {.example #module-services-emacs-querying-packages}
+### Querying Emacs packages
+
 ```
 nix-env -f "<nixpkgs>" -qaP -A emacs.pkgs.elpaPackages
 nix-env -f "<nixpkgs>" -qaP -A emacs.pkgs.melpaPackages
 nix-env -f "<nixpkgs>" -qaP -A emacs.pkgs.melpaStablePackages
 nix-env -f "<nixpkgs>" -qaP -A emacs.pkgs.orgPackages
 ```
+:::
 
 If you are on NixOS, you can install this particular Emacs for all users by
 adding it to the list of system packages (see
 [](#sec-declarative-package-mgmt)). Simply modify your file
 {file}`configuration.nix` to make it contain:
-[]{#module-services-emacs-configuration-nix}
+::: {.example #module-services-emacs-configuration-nix}
+### Custom Emacs in `configuration.nix`
+
 ```
 {
  environment.systemPackages = [
@@ -179,6 +186,7 @@ adding it to the list of system packages (see
   ];
 }
 ```
+:::
 
 In this case, the next {command}`nixos-rebuild switch` will take
 care of adding your {command}`emacs` to the {var}`PATH`
@@ -192,14 +200,17 @@ If you are not on NixOS or want to install this particular Emacs only for
 yourself, you can do so by adding it to your
 {file}`~/.config/nixpkgs/config.nix` (see
 [Nixpkgs manual](https://nixos.org/nixpkgs/manual/#sec-modify-via-packageOverrides)):
-[]{#module-services-emacs-config-nix}
+::: {.example #module-services-emacs-config-nix}
+### Custom Emacs in `~/.config/nixpkgs/config.nix`
+
 ```
 {
   packageOverrides = super: let self = super.pkgs; in {
     myemacs = import /path/to/emacs.nix { pkgs = self; };
   };
 }
 ```
+:::
 
 In this case, the next `nix-env -f '<nixpkgs>' -iA
 myemacs` will take care of adding your emacs to the
@@ -214,7 +225,9 @@ automatically generated {file}`emacs.desktop` (useful if you
 only use {command}`emacsclient`), you can change your file
 {file}`emacs.nix` in this way:
 
-[]{#ex-emacsGtk3Nix}
+::: {.example #ex-emacsGtk3Nix}
+### Custom Emacs build
+
 ```
 { pkgs ? import <nixpkgs> {} }:
 let
@@ -231,8 +244,9 @@ let
   });
 in [...]
 ```
+:::
 
-After building this file as shown in [the example above](#ex-emacsNix), you
+After building this file as shown in [](#ex-emacsNix), you
 will get an GTK 3-based Emacs binary pre-loaded with your favorite packages.
 
 ## Running Emacs as a Service {#module-services-emacs-running}
@@ -327,7 +341,10 @@ This will add the symlink
 
 The Emacs init file should be changed to load the extension packages at
 startup:
-[]{#module-services-emacs-package-initialisation}
+
+::: {.example #module-services-emacs-package-initialisation}
+### Package initialization in `.emacs`
+
 ```
 (require 'package)
 
@@ -337,6 +354,7 @@ startup:
 (setq package-enable-at-startup nil)
 (package-initialize)
 ```
+:::
 
 After the declarative emacs package configuration has been tested,
 previously downloaded packages can be cleaned up by removing
@@ -377,7 +395,9 @@ To install the DocBook 5.0 schemas, either add
 Then customize the variable {var}`rng-schema-locating-files` to
 include {file}`~/.emacs.d/schemas.xml` and put the following
 text into that file:
-[]{#ex-emacs-docbook-xml}
+::: {.example #ex-emacs-docbook-xml}
+### nXML Schema Configuration (`~/.emacs.d/schemas.xml`)
+
 ```xml
 <?xml version="1.0"?>
 <!--
@@ -397,3 +417,4 @@ text into that file:
   -->
 </locatingRules>
 ```
+:::

pkgs/tools/nix/nixos-render-docs/src/nixos_render_docs/docbook.py

@@ -218,11 +218,15 @@ def heading_close(self, token: Token, tokens: Sequence[Token], i: int) -> str:
             result += f"<partintro{maybe_id}>"
         return result
     def example_open(self, token: Token, tokens: Sequence[Token], i: int) -> str:
-        if id := token.attrs.get('id'):
-            return f"<anchor xml:id={quoteattr(cast(str, id))} />"
-        return ""
+        if id := cast(str, token.attrs.get('id', '')):
+            id = f'xml:id={quoteattr(id)}' if id else ''
+        return f'<example {id}>'
     def example_close(self, token: Token, tokens: Sequence[Token], i: int) -> str:
-        return ""
+        return "</example>"
+    def example_title_open(self, token: Token, tokens: Sequence[Token], i: int) -> str:
+        return "<title>"
+    def example_title_close(self, token: Token, tokens: Sequence[Token], i: int) -> str:
+        return "</title>"
 
     def _close_headings(self, level: Optional[int]) -> str:
         # we rely on markdown-it producing h{1..6} tags in token.tag for this to work

pkgs/tools/nix/nixos-render-docs/src/nixos_render_docs/html.py

@@ -214,11 +214,15 @@ def ordered_list_close(self, token: Token, tokens: Sequence[Token], i: int) -> s
         self._ordered_list_nesting -= 1;
         return "</ol></div>"
     def example_open(self, token: Token, tokens: Sequence[Token], i: int) -> str:
-        if id := token.attrs.get('id'):
-            return f'<a id="{escape(cast(str, id), True)}" />'
-        return ""
+        if id := cast(str, token.attrs.get('id', '')):
+            id = f'id="{escape(id, True)}"' if id else ''
+        return f'<div class="example"><a {id} />'
     def example_close(self, token: Token, tokens: Sequence[Token], i: int) -> str:
-        return ""
+        return '</div></div><br class="example-break" />'
+    def example_title_open(self, token: Token, tokens: Sequence[Token], i: int) -> str:
+        return '<p class="title"><strong>'
+    def example_title_close(self, token: Token, tokens: Sequence[Token], i: int) -> str:
+        return '</strong></p><div class="example-contents">'
 
     def _make_hN(self, level: int) -> tuple[str, str]:
         return f"h{min(6, max(1, level + self._hlevel_offset))}", ""