docs: improve option descriptions

lib/default.nix

@@ -3,14 +3,14 @@ args: let
   lib = args.lib or args.pkgs.lib;
   # makes it optional to pass if it's not explicitly needed
   pkgs = args.pkgs or (throw "[nix-gitlab-ci] pkgs argument was used but not set, please pass it");
-  inherit (lib) evalModules;
+  inherit (lib) evalModules trimWith;
 
   impl = import ./impl {inherit lib pkgs cilib;};
 
   cilib = {
     inherit (impl) helpers modules mkPipeline mkJobRun mkJobDeps mkJobPatched;
     utils = import ./utils.nix {inherit pkgs;};
-    version = builtins.readFile ./VERSION;
+    version = trimWith { start = true; end = true; } (builtins.readFile ./VERSION);
 
     mkCI = config:
       (evalModules {

lib/impl/modules/job.nix

@@ -9,12 +9,16 @@ in rec {
   jobConfigSubmodule = {pipelineConfig, ...}: {
     options = {
       enable = mkOption {
-        description = "Transform this job to a nix-configured one";
+        description = ''
+          Transform this job to a nix-configured one.
+        '';
         type = types.bool;
         default = pipelineConfig.nixJobsByDefault;
       };
       deps = mkOption {
-        description = "Dependencies to inject into the job before running it";
+        description = ''
+          Dependencies to inject into the job before running it.
+        '';
         type = types.listOf types.package;
         default = [];
       };
@@ -23,13 +27,17 @@ in rec {
         default = false;
         description = ''
           Cache this job using the GitLab Runner cache.
-          Warning: useful for tiny jobs, but most of the time it just takes an eternity.
+
+          !!! warning
+              useful for tiny jobs, but most of the time it just takes an eternity.
         '';
       };
       runnerCacheKey = mkOption {
         type = types.str;
         default = "$CI_JOB_NAME-$CI_COMMIT_REF_SLUG";
-        description = "Cache key to use for the runner nix cache. Requires enableRunnerCache = true";
+        description = ''
+          Cache key to use for the runner nix cache. Requires [`enableRunnerCache = true`](#pipelinesnamejobsnamenixenablerunnercache).
+        '';
       };
     };
   };
@@ -46,9 +54,18 @@ in rec {
     #
     gitlabOptions = {
       stage = mkOption {
+        description = ''
+          Pipeline stage to run this job in.
+        '';
         type = types.str;
       };
       image = mkUnsetOption {
+        description = ''
+          Container/OCI image to use for this job.
+
+          !!! warning
+              Setting this will mess with Nix-GitLab-CI, so be careful and only use for non-nix jobs.
+        '';
         type = types.str;
       };
       variables = mkUnsetOption {
@@ -78,7 +95,9 @@ in rec {
     options =
       {
         nix = mkOption {
-          description = "Nix-GitLab-CI config options for this job";
+          description = ''
+            Nix-GitLab-CI config options for this job.
+          '';
           type = types.submoduleWith {
             modules = [jobConfigSubmodule];
             specialArgs.pipelineConfig = pipelineConfig;
@@ -86,18 +105,34 @@ in rec {
           default = {};
         };
         finalConfig = mkOption {
+          description = ''
+            Final configuration of this job. (readonly)
+          '';
+          readOnly = true;
           internal = true;
           type = types.attrs;
         };
         depsDrv = mkOption {
+          description = ''
+            Derivation containing all the dependencies of this job. (readonly)
+          '';
+          readOnly = true;
           internal = true;
           type = types.package;
         };
         runnerDrv = mkOption {
+          description = ''
+            Derivation containing the script for running the job locally. (readonly)
+          '';
+          readOnly = true;
           internal = true;
           type = types.package;
         };
         packages = mkOption {
+          description = ''
+            Final packages for this job, eg. for running the job or getting it's deps. (readonly)
+          '';
+          readOnly = true;
           internal = true;
           type = types.attrsOf types.package;
         };

lib/impl/modules/pipeline.nix

@@ -46,7 +46,9 @@
     options =
       {
         nix = mkOption {
-          description = "Nix-CI config options for this pipeline";
+          description = ''
+            Nix-GitLab-CI config options for this pipeline.
+          '';
           type = types.submoduleWith {
             modules = [pipelineConfigSubmodule];
             specialArgs.rootConfig = rootConfig;
@@ -54,18 +56,24 @@
           default = {};
         };
         finalConfig = mkOption {
-          description = "Final config of the pipeline";
+          description = ''
-          internal = true;
+            Final config of the pipeline. (readonly)
+          '';
+          readOnly = true;
           type = types.attrs;
         };
         packages = mkOption {
-          description = "Final packages for use in CI";
+          description = ''
-          internal = true;
+            Final packages for use in CI. (readonly)
+          '';
+          readOnly = true;
           type = types.attrsOf types.package;
         };
         # jobs are nested to make distinguishing them from other keys in the ci config easier
         jobs = mkOption {
-          description = "Jobs for this pipeline";
+          description = ''
+            Jobs for this pipeline.
+          '';
           type = types.attrsOf (types.submoduleWith {
             modules = [jobSubmodule];
             specialArgs = {

lib/impl/modules/root.nix

@@ -9,14 +9,17 @@ in rec {
   configSubmodule = {
     options = {
       soonix = mkOption {
-        description = "Configure the soonix '.gitlab-ci.yml' generation";
+        description = ''
+          Configure the soonix `.gitlab-ci.yml` generation.
+        '';
         type = types.submodule soonixSubmodule;
         default = {};
       };
       nixJobsByDefault = mkOption {
         description = ''
           Whether to transform all jobs to nix-configured jobs by default.
-          If false, you need to set `nix.enable` for each job you want to be transformed.
+          If false, you need to set [`nix.enable`](#pipelinesnamejobsnamenixenable) 
+          for each job you want to be transformed.
         '';
         type = types.bool;
         default = true;
@@ -27,12 +30,16 @@ in rec {
   nixCiSubmodule = {config, ...}: {
     options = {
       config = mkOption {
-        description = "Configuration of Nix-GitLab-CI itself";
+        description = ''
+          Configuration of Nix-GitLab-CI itself.
+        '';
         type = types.submodule configSubmodule;
         default = {};
       };
       pipelines = mkOption {
-        description = "Defines all pipelines";
+        description = ''
+          Defines all pipelines.
+        '';
         type = types.attrsOf (types.submoduleWith {
           modules = [pipelineSubmodule];
           specialArgs.rootConfig = config.config;
@@ -41,13 +48,19 @@ in rec {
       };
 
       packages = mkOption {
-        description = "Final packages for use in CI";
+        description = ''
-        internal = true;
+          Final packages for use in CI. (readonly)
+        '';
+        readOnly = true;
         type = types.attrsOf types.package;
       };
       soonix = mkOption {
-        description = "Soonix config for .gitlab-ci.yml";
+        description = ''
-        internal = true;
+          Soonix config for generating `.gitlab-ci.yml`. (readonly)
+
+          See [`config.soonix`](#configsoonix) for configuring this.
+        '';
+        readOnly = true;
         type = types.attrs;
       };
     };

lib/impl/modules/soonix.nix

@@ -8,22 +8,30 @@ in {
   soonixSubmodule = {config, ...}: {
     options = {
       componentVersion = mkOption {
-        description = "CI/CD component version. Also get's passed to inputs → version";
+        description = ''
+          CI/CD component version. Also get's passed to inputs → version.
+        '';
         type = types.str;
         default = cilib.version;
       };
       componentUrl = mkOption {
-        description = "CI/CD component url";
+        description = ''
+          CI/CD component url.
+        '';
         type = types.str;
         default = "gitlab.com/TECHNOFAB/nix-gitlab-ci/nix-gitlab-ci";
       };
       componentInputs = mkOption {
-        description = "Extra inputs to pass to the CI/CD component";
+        description = ''
+          Extra inputs to pass to the CI/CD component.
+        '';
         type = types.attrs;
         default = {};
       };
       extraData = mkOption {
-        description = "Extra data to include in the .gitlab-ci.yml file";
+        description = ''
+          Extra data to include in the `.gitlab-ci.yml` file.
+        '';
         type = types.attrs;
         default = {};
       };

nix/repo/docs.nix

@@ -58,6 +58,7 @@ in
           "pymdownx.superfences"
           "pymdownx.escapeall"
           "fenced_code"
+          "admonition"
         ];
       };
     };