doc: link to the homepage of each target

[ferife]

In my opinion, the docs should have a hyperlink to the relevant website or repo next to every target.
This is because some of the targeted applications have really generic names.

For example, under the heading "stylix.targets.forge.enable", there should be a hyperlink to the home page or git repo of Forge. Without this link, I am unsure which of the many programs and applications out there named Forge this is actually meant to target.

[danth]

This should be fairly easy as a continuation of #873 as it could just be added to each module's README

[trueNAHO]

In my opinion, the docs should have a hyperlink to the relevant website or repo next to every target. This is because some of the targeted applications have really generic names.

For example, under the heading "stylix.targets.forge.enable", there should be a hyperlink to the home page or git repo of Forge. Without this link, I am unsure which of the many programs and applications out there named Forge this is actually meant to target.

AFAIK, Home Manager and NixOS are not doing this either. Only Nixpkgs declares this information:

  meta = {
    homepage = "https://git-scm.com/";
    description = "Distributed version control system";
    license = lib.licenses.gpl2;
    changelog = "https://github.com/git/git/blob/v${version}/Documentation/RelNotes/${version}.txt";

    longDescription = ''
      Git, a popular distributed version control system designed to
      handle very large projects with speed and efficiency.
    '';

    platforms = lib.platforms.all;
    maintainers = with lib.maintainers; [ primeos wmertens globin kashw2 ];
    mainProgram = "git";
  };

-- https://github.com/NixOS/nixpkgs/blob/nixos-unstable/pkgs/applications/version-management/git/default.nix#L384-L398

[danth]

Only Nixpkgs declares this information

We could potentially reuse this by associating a package with each target, then substituting values from the package metadata into the documentation.

However not all targets match up with a single package, and not all packages have all the metadata we would need.

It's most likely easier to just do this manually using the module README functionality (which is now merged 🎉)

Mockup of a generated page:

---

VSCode

Open source source code editor developed by Microsoft for Windows, Linux and macOS. It includes support for debugging, embedded Git control, syntax highlighting, intelligent code completion, snippets, and code refactoring. It is also customizable, so users can change the editor's theme, keyboard shortcuts, and preferences

https://code.visualstudio.com/

From Nixpkgs metadata

Home Manager options

stylix.targets.vscode.enable

Whether to enable theming for VSCode.

Type: boolean

Default: same as stylix.autoEnable

Example: false

Declared by:

• <modules/vscode/hm.nix>

NixOS options

None provided.

[trueNAHO]

Only Nixpkgs declares this information

We could potentially reuse this by associating a package with each target, then substituting values from the package metadata into the documentation.

However not all targets match up with a single package, and not all packages have all the metadata we would need.

It's most likely easier to just do this manually using the module README functionality (which is now merged 🎉)

What about generating the documentation from a new meta attribute instead of a stringified README.md file:

{ config, lib, ... }: {
  options.stylix.targets."<TARGET>".enable =
    config.lib.stylix.mkEnableTarget "<TARGET>" true;

  config =
    lib.mkIf (config.stylix.enable && config.stylix.targets."<TARGET>".enable) {
      services."<TARGET>".settings = { /* ... */ };

      meta = {
        description = pkgs.git.meta.description;
        homepage = pkgs.git.meta.homepage;
        license = pkgs.git.meta.license;
        longDescription = pkgs.git.meta.longDescription;
      };
    };
  };
}

If some a field is unavailable or we want to override it, we simply provide our own value:

meta = {
  description = "This is a package.";
  homepage = pkgs.git.meta.homepage;
  license = pkgs.git.meta.license;
  longDescription = "This is a very useful additional description.";
};

However, it might be better to unconditionally declare meta:

{ config, lib, ... }: {
  options.stylix.targets."<TARGET>".enable =
    config.lib.stylix.mkEnableTarget "<TARGET>" true;

  config = lib.mkMerge [
    (
      lib.mkIf
      (config.stylix.enable && config.stylix.targets."<TARGET>".enable)
      { services."<TARGET>".settings = { /* ... */ }; }
    )

    (
      {
        meta = {
          description = pkgs.git.meta.description;
          homepage = pkgs.git.meta.homepage;
          license = pkgs.git.meta.license;
          longDescription = pkgs.git.meta.longDescription;
        };
      }
    )
  ];
}

Since this is somewhat cumbersome, we might want to consider guarding meta anyway, while making sure that the documentation generation process enables all modules. However, LSPs might not display the module's meta field in that case.

[danth]

How about having meta be a separate file? That way we don't have to deal with lib.mkMerge and other complications within the module itself. It also means the metadata is not duplicated for modules which support more than one platform.

metadata.nix could look something like

pkgs: {
  inherit (pkgs.git.meta) homepage description longDescription;
}

IMO the license isn't relevant to Stylix documentation as we aren't a package manager. We just need enough details to distinguish between multiple programs with the same name.

Note that even if we add structured metadata, supporting README.md for modules is still important to be able to add extra instructions - and better than inlining this into a Nix file as README.md is rendered when browsing on GitHub, can be previewed in pull request diffs, etc

[trueNAHO]

How about having meta be a separate file? That way we don't have to deal with lib.mkMerge and other complications within the module itself. It also means the metadata is not duplicated for modules which support more than one platform.

metadata.nix could look something like

pkgs: {
  inherit (pkgs.git.meta) homepage description longDescription;
}

IMO the license isn't relevant to Stylix documentation as we aren't a package manager. We just need enough details to distinguish between multiple programs with the same name.

Sounds great. However, renaming the file to meta.nix would make the link with the conventional meta attribute set more straightforward.

Note that even if we add structured metadata, supporting README.md for modules is still important to be able to add extra instructions - and better than inlining this into a Nix file as README.md is rendered when browsing on GitHub, can be previewed in pull request diffs, etc

The meta.nix file could provide an optional extraDescription field.

I do not know how beneficial a README.md file is over inlining it into meta.nix. From the perspective of the code, this is introduces a negligible builtins.readFile indirection. From the perspective of developers, an additional file is created (which is not necessarily bad in this case) and the markdown is rendered inside the GitHub UI. Since, I very rarely browse the GitHub UI, I am unsure how beneficial this is, considering that this introduces an additional indirection for reading all meta values in one place. Either way, I find the markdown code often easier to read than its rendered version.

[danth]

README is copied directly from the source by a bash script, so there's no builtins.readFile:

https://github.com/danth/stylix/blob/master/docs/default.nix#L140

[Flameopathic]

having something like meta.nix would help with #275