From ed75ed66957126397817969647eb29daed923448 Mon Sep 17 00:00:00 2001 From: technofab Date: Wed, 27 Aug 2025 11:22:26 +0200 Subject: [PATCH] docs: add initial docs base --- LICENSE.md | 22 ++++++++++++++++ docs/index.md | 1 + docs/options.md | 3 +++ flake.nix | 2 ++ lib/module.nix | 26 +++++++++---------- nix/repo/docs.nix | 63 +++++++++++++++++++++++++++++++++++++++++++++ nix/repo/flake.lock | 18 +++++++++++++ nix/repo/flake.nix | 2 ++ 8 files changed, 124 insertions(+), 13 deletions(-) create mode 100644 LICENSE.md create mode 100644 docs/index.md create mode 100644 docs/options.md create mode 100644 nix/repo/docs.nix diff --git a/LICENSE.md b/LICENSE.md new file mode 100644 index 0000000..0bf2529 --- /dev/null +++ b/LICENSE.md @@ -0,0 +1,22 @@ +MIT License + +Copyright (c) 2025 TECHNOFAB +Copyright (c) 2022 Joshua Gilman + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. diff --git a/docs/index.md b/docs/index.md new file mode 100644 index 0000000..36a0d45 --- /dev/null +++ b/docs/index.md @@ -0,0 +1 @@ +# Soonix diff --git a/docs/options.md b/docs/options.md new file mode 100644 index 0000000..4ca74a4 --- /dev/null +++ b/docs/options.md @@ -0,0 +1,3 @@ +# Options + +{% include 'options.md' %} diff --git a/flake.nix b/flake.nix index f7d0255..f143c7f 100644 --- a/flake.nix +++ b/flake.nix @@ -21,11 +21,13 @@ cellBlocks = with ren.blocks; [ (simple "devShells") (simple "tests") + (simple "docs") ]; } { packages = ren.select self [ ["repo" "tests"] + ["repo" "docs"] ]; }; } diff --git a/lib/module.nix b/lib/module.nix index 16efd0a..19b48c5 100644 --- a/lib/module.nix +++ b/lib/module.nix @@ -24,24 +24,24 @@ in { output = mkOption { type = types.str; - description = "The relative path where the generated file should be placed"; + description = "The relative path where the generated file should be placed."; }; generator = mkOption { type = types.enum ["nix" "string" "derivation" "gotmpl" "jinja" "template"]; - description = "Which engine to use for content generation"; + description = "Which engine to use for content generation."; default = "nix"; }; data = mkOption { type = types.anything; - description = "The input data for the chosen generator"; + description = "The input data for the chosen generator."; }; opts = mkOption { type = types.attrs; default = {}; - description = "Generator-specific options"; + description = "Generator-specific options."; }; hook = mkOption { @@ -50,31 +50,31 @@ in { mode = mkOption { type = types.enum ["link" "copy"]; default = "link"; - description = "How the file should be managed (link or copy)"; + description = "How the file should be managed (link or copy)."; }; gitignore = mkOption { type = types.bool; default = true; - description = "Whether to add the output path to .gitignore"; + description = "Whether to add the output path to .gitignore."; }; extra = mkOption { type = types.str; default = ""; - description = "Additional bash commands to execute after file operation"; + description = "Additional bash commands to execute after file operation."; }; }; }; default = {}; - description = "Hook-specific options for file management"; + description = "Hook-specific options."; }; generatedDerivation = mkOption { type = types.package; internal = true; readOnly = true; - description = "The generated derivation for this file"; + description = "The generated derivation for this file."; }; }; @@ -87,24 +87,24 @@ in { }; })); default = {}; - description = "Configuration hooks for file generation and management"; + description = "Configuration of the hooks."; }; shellHook = mkOption { type = types.str; readOnly = true; - description = "Generated shell hook script for managing all files"; + description = "Generated shell hook script (as a string) for managing all files (readonly)."; }; shellHookFile = mkOption { type = types.package; readOnly = true; - description = "Generated shell hook script for managing all files"; + description = "Generated shell hook script for managing all files (readonly)."; }; finalFiles = mkOption { type = types.package; readOnly = true; - description = "Aggregated derivation containing all managed files"; + description = "Aggregated derivation containing all managed files (readonly)."; }; }; diff --git a/nix/repo/docs.nix b/nix/repo/docs.nix new file mode 100644 index 0000000..4c1e755 --- /dev/null +++ b/nix/repo/docs.nix @@ -0,0 +1,63 @@ +{inputs, ...}: let + inherit (inputs) pkgs soonix doclib; + + optionsDoc = doclib.mkOptionDocs { + module = soonix.module; + roots = [ + { + url = "https://gitlab.com/TECHNOFAB/soonix/-/blob/main/lib"; + path = "${inputs.self}/lib"; + } + ]; + }; + optionsDocs = pkgs.runCommand "options-docs" {} '' + mkdir -p $out + ln -s ${optionsDoc} $out/options.md + ''; +in + (doclib.mkDocs { + docs."default" = { + base = "${inputs.self}"; + path = "${inputs.self}/docs"; + material = { + enable = true; + umami = { + enable = true; + src = "https://analytics.tf/umami"; + siteId = "e8b0ca9c-c540-41b0-8eb8-1b2fcc5e57f7"; + domains = ["soonix.projects.tf"]; + }; + }; + macros = { + enable = true; + includeDir = toString optionsDocs; + }; + config = { + site_name = "Soonix"; + repo_name = "TECHNOFAB/soonix"; + repo_url = "https://gitlab.com/TECHNOFAB/soonix"; + theme = { + logo = "images/logo.png"; + icon.repo = "simple/gitlab"; + favicon = "images/favicon.png"; + }; + nav = [ + {"Introduction" = "index.md";} + {"Options" = "options.md";} + ]; + markdown_extensions = [ + { + "pymdownx.highlight".pygments_lang_class = true; + } + "pymdownx.inlinehilite" + "pymdownx.snippets" + "pymdownx.superfences" + "pymdownx.escapeall" + "fenced_code" + ]; + }; + }; + }).packages + // { + inherit optionsDocs; + } diff --git a/nix/repo/flake.lock b/nix/repo/flake.lock index 38a8c55..f19d0df 100644 --- a/nix/repo/flake.lock +++ b/nix/repo/flake.lock @@ -17,6 +17,23 @@ "type": "gitlab" } }, + "nixmkdocs": { + "locked": { + "dir": "lib", + "lastModified": 1755785622, + "narHash": "sha256-xBb9PCkszmrWSEqUiPC7oBJABm1thF572S5QHtloZ+M=", + "owner": "TECHNOFAB", + "repo": "nixmkdocs", + "rev": "61da605a9bff12f66c4b743f43aea59ca200f533", + "type": "gitlab" + }, + "original": { + "dir": "lib", + "owner": "TECHNOFAB", + "repo": "nixmkdocs", + "type": "gitlab" + } + }, "nixtest-lib": { "locked": { "dir": "lib", @@ -37,6 +54,7 @@ "root": { "inputs": { "devshell-lib": "devshell-lib", + "nixmkdocs": "nixmkdocs", "nixtest-lib": "nixtest-lib" } } diff --git a/nix/repo/flake.nix b/nix/repo/flake.nix index e2b6bf6..69c4f22 100644 --- a/nix/repo/flake.nix +++ b/nix/repo/flake.nix @@ -2,12 +2,14 @@ inputs = { devshell-lib.url = "gitlab:rensa-nix/devshell?dir=lib"; nixtest-lib.url = "gitlab:TECHNOFAB/nixtest?dir=lib"; + nixmkdocs.url = "gitlab:TECHNOFAB/nixmkdocs?dir=lib"; }; outputs = i: i // { ntlib = i.nixtest-lib.lib {inherit (i.parent) pkgs;}; devshell = i.devshell-lib.lib {inherit (i.parent) pkgs;}; + doclib = i.nixmkdocs.lib {inherit (i.parent) pkgs;}; soonix = import "${i.parent.self}/lib" {inherit (i.parent) pkgs;}; }; }