From a9eee479912be7d3bea61999be5b39d4801ec0d4 Mon Sep 17 00:00:00 2001 From: Pyrox Date: Sun, 30 Jun 2024 01:43:43 -0400 Subject: [PATCH] initial commit --- .envrc | 4 + .gitignore | 7 ++ assets/aux-logo.svg | 34 +++++ flake.lock | 118 ++++++++++++++++++ flake.nix | 50 ++++++++ mkdocs-hooks/fonts.py | 5 + mkdocs.yml | 36 ++++++ nixpkgs-doc/doc-support/lib-function-docs.nix | 51 ++++++++ .../doc-support/lib-function-locations.nix | 85 +++++++++++++ .../doc-support/python-interpreter-table.nix | 63 ++++++++++ nixpkgs-doc/libsets.nix | 79 ++++++++++++ nixpkgs-doc/manual-assets.nix | 14 +++ nixpkgs-doc/md-manual.nix | 81 ++++++++++++ nixpkgs-doc/nixpkgs-doc.nix | 13 ++ nixpkgs-doc/options-doc.nix | 32 +++++ shells/default/default.nix | 24 ++++ 16 files changed, 696 insertions(+) create mode 100644 .envrc create mode 100644 .gitignore create mode 100644 assets/aux-logo.svg create mode 100644 flake.lock create mode 100644 flake.nix create mode 100644 mkdocs-hooks/fonts.py create mode 100644 mkdocs.yml create mode 100644 nixpkgs-doc/doc-support/lib-function-docs.nix create mode 100644 nixpkgs-doc/doc-support/lib-function-locations.nix create mode 100644 nixpkgs-doc/doc-support/python-interpreter-table.nix create mode 100644 nixpkgs-doc/libsets.nix create mode 100644 nixpkgs-doc/manual-assets.nix create mode 100644 nixpkgs-doc/md-manual.nix create mode 100644 nixpkgs-doc/nixpkgs-doc.nix create mode 100644 nixpkgs-doc/options-doc.nix create mode 100644 shells/default/default.nix diff --git a/.envrc b/.envrc new file mode 100644 index 0000000..f41a01c --- /dev/null +++ b/.envrc @@ -0,0 +1,4 @@ +if ! has nix_direnv_version || ! nix_direnv_version 3.0.5; then + source_url "https://raw.githubusercontent.com/nix-community/nix-direnv/3.0.5/direnvrc" "sha256-RuwIS+QKFj/T9M2TFXScjBsLR6V3A17YVoEW/Q6AZ1w=" +fi +use flake diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..7bec352 --- /dev/null +++ b/.gitignore @@ -0,0 +1,7 @@ +result +.direnv +book +docs/nixpkgs-doc +docs +.cache/plugin/social +mkdocs-hooks/__pycache__ diff --git a/assets/aux-logo.svg b/assets/aux-logo.svg new file mode 100644 index 0000000..46040ca --- /dev/null +++ b/assets/aux-logo.svg @@ -0,0 +1,34 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + \ No newline at end of file diff --git a/flake.lock b/flake.lock new file mode 100644 index 0000000..a157706 --- /dev/null +++ b/flake.lock @@ -0,0 +1,118 @@ +{ + "nodes": { + "flake-compat": { + "flake": false, + "locked": { + "lastModified": 1650374568, + "narHash": "sha256-Z+s0J8/r907g149rllvwhb4pKi8Wam5ij0st8PwAh+E=", + "owner": "edolstra", + "repo": "flake-compat", + "rev": "b4a34015c698c7793d592d66adbab377907a2be8", + "type": "github" + }, + "original": { + "owner": "edolstra", + "repo": "flake-compat", + "type": "github" + } + }, + "flake-utils": { + "inputs": { + "systems": "systems" + }, + "locked": { + "lastModified": 1694529238, + "narHash": "sha256-zsNZZGTGnMOf9YpHKJqMSsa0dXbfmxeoJ7xHlrt+xmY=", + "owner": "numtide", + "repo": "flake-utils", + "rev": "ff7b65b44d01cf9ba6a71320833626af21126384", + "type": "github" + }, + "original": { + "owner": "numtide", + "repo": "flake-utils", + "type": "github" + } + }, + "flake-utils-plus": { + "inputs": { + "flake-utils": "flake-utils" + }, + "locked": { + "lastModified": 1715533576, + "narHash": "sha256-fT4ppWeCJ0uR300EH3i7kmgRZnAVxrH+XtK09jQWihk=", + "owner": "gytis-ivaskevicius", + "repo": "flake-utils-plus", + "rev": "3542fe9126dc492e53ddd252bb0260fe035f2c0f", + "type": "github" + }, + "original": { + "owner": "gytis-ivaskevicius", + "repo": "flake-utils-plus", + "rev": "3542fe9126dc492e53ddd252bb0260fe035f2c0f", + "type": "github" + } + }, + "nixpkgs": { + "locked": { + "lastModified": 1719468428, + "narHash": "sha256-vN5xJAZ4UGREEglh3lfbbkIj+MPEYMuqewMn4atZFaQ=", + "owner": "nixos", + "repo": "nixpkgs", + "rev": "1e3deb3d8a86a870d925760db1a5adecc64d329d", + "type": "github" + }, + "original": { + "owner": "nixos", + "ref": "nixpkgs-unstable", + "repo": "nixpkgs", + "type": "github" + } + }, + "root": { + "inputs": { + "nixpkgs": "nixpkgs", + "snowfall-lib": "snowfall-lib" + } + }, + "snowfall-lib": { + "inputs": { + "flake-compat": "flake-compat", + "flake-utils-plus": "flake-utils-plus", + "nixpkgs": [ + "nixpkgs" + ] + }, + "locked": { + "lastModified": 1719005984, + "narHash": "sha256-mpFl3Jv4fKnn+5znYXG6SsBjfXHJdRG5FEqNSPx0GLA=", + "owner": "snowfallorg", + "repo": "lib", + "rev": "c6238c83de101729c5de3a29586ba166a9a65622", + "type": "github" + }, + "original": { + "owner": "snowfallorg", + "repo": "lib", + "type": "github" + } + }, + "systems": { + "locked": { + "lastModified": 1681028828, + "narHash": "sha256-Vy1rq5AaRuLzOxct8nz4T6wlgyUR7zLU309k9mBC768=", + "owner": "nix-systems", + "repo": "default", + "rev": "da67096a3b9bf56a91d16901293e51ba5b49a27e", + "type": "github" + }, + "original": { + "owner": "nix-systems", + "repo": "default", + "type": "github" + } + } + }, + "root": "root", + "version": 7 +} diff --git a/flake.nix b/flake.nix new file mode 100644 index 0000000..4a1b3e7 --- /dev/null +++ b/flake.nix @@ -0,0 +1,50 @@ +{ + description = "Aux Manual Generator"; + + inputs.nixpkgs.url = "github:nixos/nixpkgs/nixpkgs-unstable"; + inputs.snowfall-lib = { + url = "github:snowfallorg/lib"; + inputs.nixpkgs.follows = "nixpkgs"; + }; + + outputs = + inputs@{ self, ... }: + inputs.snowfall-lib.mkFlake { + inherit inputs; + src = ./.; + snowfall = { + namespace = "amg"; + meta = { + name = "aux-manual-gen"; + title = "Aux Manual Generator"; + }; + }; + outputs-builder = + channels: + let + pkgs = channels.nixpkgs; + spkgs = self.packages.${pkgs.system}; + libsets = (import ./nixpkgs-doc/libsets.nix); + in + { + packages = { + lib-docs = pkgs.callPackage ./nixpkgs-doc/doc-support/lib-function-docs.nix { + inherit + libsets + pkgs + spkgs + inputs + ; + }; + doc-locations-json = pkgs.callPackage ./nixpkgs-doc/doc-support/lib-function-locations.nix { + inherit libsets pkgs; + }; + md-manual = pkgs.callPackage ./nixpkgs-doc/md-manual.nix { inherit spkgs inputs; }; + python-interp-table = pkgs.callPackage ./nixpkgs-doc/doc-support/python-interpreter-table.nix { }; + options-doc = pkgs.callPackage ./nixpkgs-doc/options-doc.nix { inherit pkgs inputs; }; + nixpkgs-doc = pkgs.callPackage ./nixpkgs-doc/nixpkgs-doc.nix { inherit inputs; }; + manual-assets = pkgs.callPackage ./nixpkgs-doc/manual-assets.nix { }; + }; + }; + }; +} diff --git a/mkdocs-hooks/fonts.py b/mkdocs-hooks/fonts.py new file mode 100644 index 0000000..7b8e04d --- /dev/null +++ b/mkdocs-hooks/fonts.py @@ -0,0 +1,5 @@ +def on_post_page(output, page, config): + return output.replace( + "https://fonts.googleapis.com/css", + "https://fonts.bunny.net/css" + ) diff --git a/mkdocs.yml b/mkdocs.yml new file mode 100644 index 0000000..381e0f2 --- /dev/null +++ b/mkdocs.yml @@ -0,0 +1,36 @@ +site_name: Aux Docs +site_url: https://auxdocs.pyrox.dev/ +theme: + name: material + features: + - search.highlight + font: + text: IBM Plex Sans + code: IBM Plex Mono + language: en + logo: assets/aux-logo.svg +hooks: + - mkdocs-hooks/fonts.py +plugins: + - search + - social +markdown_extensions: + - admonition + - attr_list + - pymdownx.details + - pymdownx.emoji: + emoji_index: !!python/name:material.extensions.emoji.twemoji + emoji_generator: !!python/name:material.extensions.emoji.to_svg + - pymdownx.highlight + - pymdownx.superfences +extra: + social: + - icon: simple/forgejo + link: https://git.pyrox.dev/pyrox/aux-docs + name: Aux Docs Repo + - icon: simple/discourse + link: https://forum.aux.computer/ + name: Aux Forum + - icon: simple/wikidotjs + link: https://wiki.auxolotl.org/ + name: Aux Wiki diff --git a/nixpkgs-doc/doc-support/lib-function-docs.nix b/nixpkgs-doc/doc-support/lib-function-docs.nix new file mode 100644 index 0000000..90e4b97 --- /dev/null +++ b/nixpkgs-doc/doc-support/lib-function-docs.nix @@ -0,0 +1,51 @@ +# Generates the documentation for library functions via nixdoc. +{ + pkgs, + spkgs, + libsets, + inputs, +}: +let + + inherit (pkgs) stdenv lib nixdoc; + +in +stdenv.mkDerivation { + name = "nixpkgs-lib-docs"; + src = "${inputs.nixpkgs.outPath}/lib"; + + buildInputs = [ nixdoc ]; + installPhase = '' + function docgen { + name=$1 + baseName=$2 + description=$3 + # TODO: wrap lib.$name in , make nixdoc not escape it + if [[ -e "../lib/$baseName.nix" ]]; then + nixdoc -c "$name" -d "lib.$name: $description" -l ${spkgs.doc-locations-json} -f "$baseName.nix" > "$out/$name.md" + else + nixdoc -c "$name" -d "lib.$name: $description" -l ${spkgs.doc-locations-json} -f "$baseName/default.nix" > "$out/$name.md" + fi + echo "$out/$name.md" >> "$out/index.md" + } + + mkdir -p "$out" + + cat > "$out/index.md" << 'EOF' + ```{=include=} sections auto-id-prefix=auto-generated + EOF + + ${lib.concatMapStrings ( + { + name, + baseName ? name, + description, + }: + '' + docgen ${name} ${baseName} ${lib.escapeShellArg description} + '' + ) libsets} + + echo '```' >> "$out/index.md" + ''; +} diff --git a/nixpkgs-doc/doc-support/lib-function-locations.nix b/nixpkgs-doc/doc-support/lib-function-locations.nix new file mode 100644 index 0000000..4fff40f --- /dev/null +++ b/nixpkgs-doc/doc-support/lib-function-locations.nix @@ -0,0 +1,85 @@ +{ + pkgs, + nixpkgs ? { }, + libsets, +}: +let + revision = pkgs.lib.trivial.revisionWithDefault (nixpkgs.rev or "master"); + + libDefPos = + prefix: set: + builtins.concatMap ( + name: + [ + { + name = builtins.concatStringsSep "." (prefix ++ [ name ]); + location = builtins.unsafeGetAttrPos name set; + } + ] + ++ nixpkgsLib.optionals (builtins.length prefix == 0 && builtins.isAttrs set.${name}) ( + libDefPos (prefix ++ [ name ]) set.${name} + ) + ) (builtins.attrNames set); + + libset = + toplib: + builtins.map (subsetname: { + subsetname = subsetname; + functions = libDefPos [ ] toplib.${subsetname}; + }) (builtins.map (x: x.name) libsets); + + nixpkgsLib = pkgs.lib; + + flattenedLibSubset = + { subsetname, functions }: + builtins.map (fn: { + name = "lib.${subsetname}.${fn.name}"; + value = fn.location; + }) functions; + + locatedlibsets = libs: builtins.map flattenedLibSubset (libset libs); + removeFilenamePrefix = + prefix: filename: + let + prefixLen = (builtins.stringLength prefix) + 1; # +1 to remove the leading / + filenameLen = builtins.stringLength filename; + substr = builtins.substring prefixLen filenameLen filename; + in + substr; + + removeNixpkgs = removeFilenamePrefix (builtins.toString pkgs.path); + + liblocations = builtins.filter (elem: elem.value != null) ( + nixpkgsLib.lists.flatten (locatedlibsets nixpkgsLib) + ); + + fnLocationRelative = + { name, value }: + { + inherit name; + value = value // { + file = removeNixpkgs value.file; + }; + }; + + relativeLocs = (builtins.map fnLocationRelative liblocations); + sanitizeId = builtins.replaceStrings [ "'" ] [ "-prime" ]; + + urlPrefix = "https://github.com/NixOS/nixpkgs/blob/${revision}"; + jsonLocs = builtins.listToAttrs ( + builtins.map ( + { name, value }: + { + name = sanitizeId name; + value = + let + text = "${value.file}:${builtins.toString value.line}"; + target = "${urlPrefix}/${value.file}#L${builtins.toString value.line}"; + in + "[${text}](${target}) in ``"; + } + ) relativeLocs + ); + +in +pkgs.writeText "locations.json" (builtins.toJSON jsonLocs) diff --git a/nixpkgs-doc/doc-support/python-interpreter-table.nix b/nixpkgs-doc/doc-support/python-interpreter-table.nix new file mode 100644 index 0000000..6f2b342 --- /dev/null +++ b/nixpkgs-doc/doc-support/python-interpreter-table.nix @@ -0,0 +1,63 @@ +# For debugging, run in this directory: +# nix eval --impure --raw --expr 'import ./python-interpreter-table.nix {}' +{ pkgs ? (import ../.. { config = { }; overlays = []; }) }: +let + lib = pkgs.lib; + inherit (lib.attrsets) attrNames filterAttrs; + inherit (lib.lists) elem filter map naturalSort reverseList; + inherit (lib.strings) concatStringsSep; + + isPythonInterpreter = name: + /* NB: Package names that don't follow the regular expression: + - `python-cosmopolitan` is not part of `pkgs.pythonInterpreters`. + - `_prebuilt` interpreters are used for bootstrapping internally. + - `python3Minimal` contains python packages, left behind conservatively. + - `rustpython` lacks `pythonVersion` and `implementation`. + */ + (lib.strings.match "(pypy|python)([[:digit:]]*)" name) != null; + + interpreterName = pname: + let + cuteName = { + cpython = "CPython"; + pypy = "PyPy"; + }; + interpreter = pkgs.${pname}; + in + "${cuteName.${interpreter.implementation}} ${interpreter.pythonVersion}"; + + interpreters = reverseList (naturalSort ( + filter isPythonInterpreter (attrNames pkgs.pythonInterpreters) + )); + + aliases = pname: + attrNames ( + filterAttrs (name: value: + isPythonInterpreter name + && name != pname + && interpreterName name == interpreterName pname + ) pkgs + ); + + result = map (pname: { + inherit pname; + aliases = aliases pname; + interpreter = interpreterName pname; + }) interpreters; + + toMarkdown = data: + let + line = package: '' + | ${package.pname} | ${join ", " package.aliases or [ ]} | ${package.interpreter} | + ''; + in + join "" (map line data); + + join = lib.strings.concatStringsSep; + +in +'' + | Package | Aliases | Interpeter | + |---------|---------|------------| + ${toMarkdown result} +'' diff --git a/nixpkgs-doc/libsets.nix b/nixpkgs-doc/libsets.nix new file mode 100644 index 0000000..8fa1982 --- /dev/null +++ b/nixpkgs-doc/libsets.nix @@ -0,0 +1,79 @@ +[ + { + name = "asserts"; + description = "assertion functions"; + } + { + name = "attrsets"; + description = "attribute set functions"; + } + { + name = "strings"; + description = "string manipulation functions"; + } + { + name = "versions"; + description = "version string functions"; + } + { + name = "trivial"; + description = "miscellaneous functions"; + } + { + name = "fixedPoints"; + baseName = "fixed-points"; + description = "explicit recursion functions"; + } + { + name = "lists"; + description = "list manipulation functions"; + } + { + name = "debug"; + description = "debugging functions"; + } + { + name = "options"; + description = "NixOS / nixpkgs option handling"; + } + { + name = "path"; + description = "path functions"; + } + { + name = "filesystem"; + description = "filesystem functions"; + } + { + name = "fileset"; + description = "file set functions"; + } + { + name = "sources"; + description = "source filtering functions"; + } + { + name = "cli"; + description = "command-line serialization functions"; + } + { + name = "generators"; + description = "functions that create file formats from nix data structures"; + } + { + name = "gvariant"; + description = "GVariant formatted string serialization functions"; + } + { + name = "customisation"; + description = "Functions to customise (derivation-related) functions, derivatons, or attribute sets"; + } + { + name = "meta"; + description = "functions for derivation metadata"; + } + { + name = "derivations"; + description = "miscellaneous derivation-specific functions"; + } +] diff --git a/nixpkgs-doc/manual-assets.nix b/nixpkgs-doc/manual-assets.nix new file mode 100644 index 0000000..063380f --- /dev/null +++ b/nixpkgs-doc/manual-assets.nix @@ -0,0 +1,14 @@ +{ stdenvNoCC }: +stdenvNoCC.mkDerivation { + pname = "aux-manual-assets"; + version = "0.0.0"; + + src = ../assets; + + phases = "installPhase"; + + installPhase = '' + mkdir $out + cp $src/* $out + ''; +} diff --git a/nixpkgs-doc/md-manual.nix b/nixpkgs-doc/md-manual.nix new file mode 100644 index 0000000..4859f9c --- /dev/null +++ b/nixpkgs-doc/md-manual.nix @@ -0,0 +1,81 @@ +{ + lib, + nixos-render-docs, + python3, + perl, + stdenvNoCC, + spkgs, + inputs, +}: +stdenvNoCC.mkDerivation { + name = "nixpkgs-manual-md"; + + nativeBuildInputs = [ + nixos-render-docs + python3 + perl + ]; + + src = inputs.nixpkgs; + + patchPhase = '' + cd doc + find . -type f ! -name '*.md' ! -name '*.md.in' -exec rm {} \+ + ''; + + postPatch = '' + ln -s ${spkgs.options-doc.optionsJSON}/share/doc/nixos/options.json ./config-options.json + ''; + + pythonInterpreterTable = spkgs.python-interp-table; + + passAsFile = [ "pythonInterpreterTable" ]; + + buildPhase = '' + substituteInPlace ./languages-frameworks/python.section.md --subst-var-by python-interpreter-table "$(<"$pythonInterpreterTablePath")" + + cat \ + ./functions/library.md.in \ + ${spkgs.lib-docs}/index.md \ + > ./functions/library.md + substitute ./manual.md.in ./manual.md \ + --replace-fail '@MANUAL_VERSION@' '${lib.version}' + + mkdir out + + mkdir out/assets + cp ${spkgs.manual-assets}/* out/assets/ + + mv preface.chapter.md out/index.md + mv build-helpers out/build-helpers + mv build-helpers.md out/build-helpers/index.md + mv contributing out/contributing + mv contributing.md out/contributing/index.md + mv development out/development + mv development.md out/development/index.md + mv functions out/functions + mv functions.md out/functions/index.md + mv hooks out/hooks + mv languages-frameworks out/languages-frameworks + mkdir out/lib + cp ${spkgs.lib-docs}/*.md out/lib/ + mv module-system out/module-system + mv packages out/packages + mv stdenv out/stdenv + mv stdenv.md out/stdenv/index.md + mv using out/using + mv using-nixpkgs.md out/using/index.md + pushd out + find . -type f -exec perl -pi -e 's/\s*:::{.note}\n/!!! note\n\ \ /' {} \; + find . -type f -exec perl -pi -e 's/\s*:::{.warning}\n/!!! warning\n\ \ /' {} \; + find . -type f -exec perl -pi -e 's/\s*:::{.tip}\n/!!! tip\n\ \ \ \ /' {} \; + find . -type f -exec perl -pi -e 's/\s*:::{.example}\n/!!! example\n\ \ \ \ /' {} \; + find . -type f -exec sed -i 's/\s*::://g' {} \; + popd + ''; + + installPhase = '' + mkdir $out + mv out/* $out + ''; +} diff --git a/nixpkgs-doc/nixpkgs-doc.nix b/nixpkgs-doc/nixpkgs-doc.nix new file mode 100644 index 0000000..b8022c2 --- /dev/null +++ b/nixpkgs-doc/nixpkgs-doc.nix @@ -0,0 +1,13 @@ +{ stdenv, inputs }: +stdenv.mkDerivation { + pname = "nixpkgs-doc-src"; + version = "unstable"; + + src = inputs.nixpkgs.outPath; + + phases = "installPhase"; + + installPhase = '' + cp -r doc/ $out + ''; +} diff --git a/nixpkgs-doc/options-doc.nix b/nixpkgs-doc/options-doc.nix new file mode 100644 index 0000000..80124c5 --- /dev/null +++ b/nixpkgs-doc/options-doc.nix @@ -0,0 +1,32 @@ +{ pkgs, inputs }: +let + inherit (pkgs.lib) hasPrefix removePrefix; +in +pkgs.nixosOptionsDoc { + inherit + (pkgs.lib.evalModules { + modules = [ "${inputs.nixpkgs.outPath}/pkgs/top-level/config.nix" ]; + class = "nixpkgsConfig"; + }) + options + ; + documentType = "none"; + transformOptions = + opt: + opt + // { + declarations = map ( + decl: + if hasPrefix (toString ../..) (toString decl) then + let + subpath = removePrefix "/" (removePrefix (toString ../.) (toString decl)); + in + { + url = "https://github.com/NixOS/nixpkgs/blob/master/${subpath}"; + name = subpath; + } + else + decl + ) opt.declarations; + }; +} diff --git a/shells/default/default.nix b/shells/default/default.nix new file mode 100644 index 0000000..077a436 --- /dev/null +++ b/shells/default/default.nix @@ -0,0 +1,24 @@ +{ pkgs, ... }: +let + customPython = pkgs.python312.withPackages (ps: [ + ps.mkdocs-material + ps.mkdocs + ps.pillow + ps.cairosvg + ]); +in +pkgs.mkShell { + buildInputs = [ + customPython + pkgs.deadnix + pkgs.nixfmt-rfc-style + pkgs.statix + pkgs.nixd + pkgs.nil + pkgs.nixdoc + pkgs.nixos-render-docs + pkgs.mdbook + pkgs.nix-tree + pkgs.mdbook-admonish + ]; +}