doc: restructure module rendering

docs/default.nix

@@ -131,38 +131,20 @@ let
 
             readme =
               let
-                path = "${inputs.self}/modules/${module}/README.md";
-
-                # This doesn't count as IFD because ${inputs.self} is a flake input
-                #
-                # In addition, this checks that the README.md starts with an
-                # appropriate title
-                mainText =
-                  let
-                    name = lib.throwIfNot (
-                      metadata ? ${module}.name
-                    ) "stylix: ${module} is missing `meta.name`" metadata.${module}.name;
-                  in
-                  if builtins.pathExists path then
-                    let
-                      text = builtins.readFile path;
-                    in
-                    lib.throwIfNot (
-                      (builtins.head (lib.splitString "\n" text)) == "# ${name}"
-                    ) "README.md of ${name} must have a title which matches its `meta.name`" text
-                  else
-                    ''
-                      # ${name}
-                      > [!NOTE]
-                      > This module doesn't include any additional documentation.
-                      > You can browse the options it provides below.
-                    '';
-
                 maintainers =
                   lib.throwIfNot (metadata ? ${module}.maintainers)
                     "stylix: ${module} is missing `meta.maintainers`"
                     metadata.${module}.maintainers;
 
+                joinItems =
+                  items:
+                  if builtins.length items <= 2 then
+                    builtins.concatStringsSep " and " items
+                  else
+                    builtins.concatStringsSep ", " (
+                      lib.dropEnd 1 items ++ [ "and ${lib.last items}" ]
+                    );
+
                 # Render a maintainer's name and a link to the best contact
                 # information we have for them.
                 #
@@ -192,34 +174,46 @@ let
                   else
                     maintainer.name;
 
-                joinItems =
-                  items:
-                  if builtins.length items <= 2 then
-                    builtins.concatStringsSep " and " items
-                  else
-                    builtins.concatStringsSep ", " (
-                      lib.dropEnd 1 items ++ [ "and ${lib.last items}" ]
-                    );
-
                 renderedMaintainers = joinItems (map renderMaintainer maintainers);
 
                 ghHandles = toString (
                   map (m: lib.optionalString (m ? github) "@${m.github}") maintainers
                 );
 
-                maintainersText =
-                  if maintainers == [ ] then
-                    "This module has no [dedicated maintainers](../../modules.md#maintainers)."
+                maintainersText = lib.optionalString (
+                  maintainers != [ ]
+                ) "**Maintainers**: ${renderedMaintainers} (`${ghHandles}`)";
+
+                # Render homepages as hyperlinks in readme
+                homepage = metadata.${module}.homepage or null;
+
+                renderedHomepages = joinItems (
+                  lib.mapAttrsToList (name: url: "[${name}](${url})") homepage
+                );
+
+                homepageText =
+                  if homepage == null then
+                    ""
+                  else if builtins.isString homepage then
+                    "**Homepage**: [${homepage}](${homepage})\n"
+                  else if builtins.isAttrs homepage then
+                    lib.throwIf (builtins.length (builtins.attrNames homepage) == 1)
+                      "stylix: ${module}: `meta.homepage.${builtins.head (builtins.attrNames homepage)}` should be simplified to `meta.homepage`"
+                      "**Homepages**: ${renderedHomepages}\n"
                   else
-                    ''
-                      This module is maintained by ${renderedMaintainers},
-                      pingable via: `${ghHandles}`.
-                    '';
+                    throw "stylix: ${module}: unexpected type for `meta.homepage`: ${builtins.typeOf homepage}";
+
+                name = lib.throwIfNot (
+                  metadata ? ${module}.name
+                ) "stylix: ${module} is missing `meta.name`" metadata.${module}.name;
+
               in
-              lib.concatLines [
-                mainText
-                "## Module information"
+              lib.concatMapStrings (paragraph: "${paragraph}\n\n") [
+                "# ${name}"
+                homepageText
                 maintainersText
+                "---"
+                metadata.${module}.description or ""
               ];
 
             # Module pages initialise all platforms to an empty list, so that

docs/src/modules.md

@@ -150,10 +150,30 @@ directly from `config`. See the reference pages for a list of options.
 Metadata is stored in `/modules/«module»/meta.nix`. The following attributes are
 available under `meta`:
 
-- `maintainers`: required list of maintainers. See [Maintainers](#maintainers)
-section.
 - `name`: required human-readable string name.
 
+- `homepage`: homepage string or attribute set of homepage strings, depending
+  on the number of homepages:
+
+  - ```nix
+    homepage = "https://github.com/danth/stylix";
+    ```
+
+  - ```nix
+    homepage = {
+      Nix = "https://github.com/NixOS/nix";
+      Nixpkgs = "https://github.com/NixOS/nixpkgs";
+    };
+    ```
+
+  The attribute names are used as hyperlink text and the attribute values are
+  used as URLs.
+
+- `maintainers`: required list of maintainers. See [Maintainers](#maintainers)
+  section.
+
+- `description`: optional markdown string for extra documentation.
+
 ### Maintainers
 
 New modules must have at least one maintainer.

modules/alacritty/meta.nix

@@ -1,4 +1,5 @@
 {
-  maintainers = [ ];
   name = "Alacritty";
+  homepage = "https://github.com/alacritty/alacritty";
+  maintainers = [ ];
 }

modules/avizo/meta.nix

@@ -1,4 +1,5 @@
 {
-  maintainers = [ ];
   name = "Avizo";
+  homepage = "https://github.com/misterdanb/avizo";
+  maintainers = [ ];
 }

modules/bat/meta.nix

@@ -1,5 +1,6 @@
 { lib, ... }:
 {
-  maintainers = [ lib.maintainers.naho ];
   name = "bat";
+  homepage = "https://github.com/sharkdp/bat";
+  maintainers = [ lib.maintainers.naho ];
 }

modules/bemenu/meta.nix

@@ -1,5 +1,6 @@
 { lib, ... }:
 {
-  maintainers = [ lib.maintainers.noodlez1232 ];
   name = "bemenu";
+  homepage = "https://github.com/Cloudef/bemenu";
+  maintainers = [ lib.maintainers.noodlez1232 ];
 }

modules/bspwm/meta.nix

@@ -1,4 +1,5 @@
 {
-  maintainers = [ ];
   name = "bspwm";
+  homepage = "https://github.com/baskerville/bspwm";
+  maintainers = [ ];
 }

modules/btop/meta.nix

@@ -1,5 +1,6 @@
 { lib, ... }:
 {
-  maintainers = [ lib.maintainers.naho ];
   name = "btop";
+  homepage = "https://github.com/aristocratos/btop";
+  maintainers = [ lib.maintainers.naho ];
 }

modules/cava/meta.nix

@@ -1,4 +1,5 @@
 {
-  maintainers = [ ];
   name = "Cava";
+  homepage = "https://github.com/karlstav/cava";
+  maintainers = [ ];
 }

modules/cavalier/meta.nix

@@ -1,4 +1,5 @@
 {
-  maintainers = [ ];
   name = "Cavalier";
+  homepage = "https://github.com/NickvisionApps/Cavalier";
+  maintainers = [ ];
 }

modules/chromium/meta.nix

@@ -1,5 +1,6 @@
 { lib, ... }:
 {
-  maintainers = [ lib.maintainers.danth ];
   name = "Chromium";
+  homepage = "https://www.chromium.org/";
+  maintainers = [ lib.maintainers.danth ];
 }

modules/console/meta.nix

@@ -1,4 +1,4 @@
 {
-  maintainers = [ ];
   name = "kernel console";
+  maintainers = [ ];
 }

modules/discord/meta.nix

@@ -1,5 +1,24 @@
 { lib, ... }:
 {
-  maintainers = [ lib.maintainers.Flameopathic ];
   name = "Discord";
+  homepage = {
+    Discord = "https://discordapp.com/";
+    Nixcord = "https://github.com/KaylorBen/nixcord";
+    Vencord = "https://github.com/Vendicated/Vencord";
+    Vesktop = "https://github.com/Vencord/Vesktop";
+  };
+  maintainers = [ lib.maintainers.Flameopathic ];
+  description = ''
+    This module provides a collection of targets related to
+    [Discord](https://discord.com). The same theme is used for each target.
+
+    The Vencord, Vesktop, and Nixcord targets use built-in Home Manager options,
+    while the Nixcord target leverages
+    [github:KaylorBen/nixcord](https://github.com/KaylorBen/nixcord).
+
+    > [!IMPORTANT]
+    > The Nixcord target will have no effect unless Nixcord is properly
+    > [imported](https://github.com/KaylorBen/nixcord?tab=readme-ov-file#how-to-use-nixcord)
+    > into your configuration.
+  '';
 }

modules/dunst/meta.nix

@@ -1,5 +1,6 @@
 { lib, ... }:
 {
-  maintainers = [ lib.maintainers.naho ];
   name = "Dunst";
+  homepage = "https://dunst-project.org/";
+  maintainers = [ lib.maintainers.naho ];
 }

modules/emacs/meta.nix

@@ -1,5 +1,6 @@
 { lib, ... }:
 {
-  maintainers = [ lib.maintainers.panchoh ];
   name = "Emacs";
+  homepage = "https://www.gnu.org/software/emacs/";
+  maintainers = [ lib.maintainers.panchoh ];
 }

modules/eog/meta.nix

@@ -1,5 +1,6 @@
 { lib, ... }:
 {
-  maintainers = [ lib.maintainers.danth ];
   name = "Eye of GNOME";
+  homepage = "https://gitlab.gnome.org/GNOME/eog";
+  maintainers = [ lib.maintainers.danth ];
 }

modules/fcitx5/meta.nix

@@ -1,5 +1,6 @@
 { lib, ... }:
 {
-  maintainers = [ lib.maintainers.make-42 ];
   name = "Fcitx 5";
+  homepage = "https://fcitx-im.org/wiki/Fcitx_5";
+  maintainers = [ lib.maintainers.make-42 ];
 }

modules/feh/meta.nix

@@ -1,4 +1,5 @@
 {
-  maintainers = [ ];
   name = "feh";
+  homepage = "https://feh.finalrewind.org/";
+  maintainers = [ ];
 }

modules/firefox/meta.nix

@@ -1,9 +1,50 @@
 { lib, ... }:
 {
+  name = "Firefox and its derivatives";
+  homepage = {
+    Firefox = "http://www.mozilla.com/en-US/firefox/";
+    Floorp = "https://floorp.app/";
+    LibreWolf = "https://librewolf.net/";
+  };
   maintainers = with lib.maintainers; [
     Flameopathic
     danth
   ];
+  description = ''
+    This module supports [Firefox](https://www.mozilla.org/firefox/), in addition
+    to [Floorp](https://floorp.app/) and [LibreWolf](https://librewolf.net/),
+    which are Firefox derivatives.
 
-  name = "Firefox and its derivatives";
+    The same implementation is shared between all of these browsers, but they don't
+    share option values.
+
+    > [!IMPORTANT]
+    >
+    > For any theming to be applied, you need to tell this module which
+    > [profiles](https://support.mozilla.org/en-US/kb/profiles-where-firefox-stores-user-data)
+    > you're using:
+    >
+    > ```nix
+    > {
+    >   programs.firefox = {
+    >     enable = true;
+    >
+    >     profiles = {
+    >       my-profile = {
+    >         # bookmarks, extensions, search engines...
+    >       };
+    >       my-friends-profile = {
+    >         # bookmarks, extensions, search engines...
+    >       };
+    >     };
+    >   };
+    >
+    >   stylix.targets.firefox.profileNames = [ "my-profile" "my-friends-profile" ];
+    > }
+    > ```
+    >
+    > This is necessary due to a limitation of the module system: we can either
+    > detect the list of profiles, or change their configuration, but we can't do
+    > both without infinite recursion.
+  '';
 }