{"id":13682624,"url":"https://github.com/lf-/nix-doc","last_synced_at":"2025-09-10T14:10:30.852Z","repository":{"id":37680051,"uuid":"280102862","full_name":"lf-/nix-doc","owner":"lf-","description":"An interactive Nix documentation tool providing a CLI for function search, a Nix plugin for docs in the REPL, and a ctags implementation for Nix script","archived":false,"fork":false,"pushed_at":"2024-05-15T22:15:48.000Z","size":186,"stargazers_count":217,"open_issues_count":9,"forks_count":6,"subscribers_count":6,"default_branch":"main","last_synced_at":"2025-06-27T11:05:00.945Z","etag":null,"topics":["nix","nix-plugin"],"latest_commit_sha":null,"homepage":"","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/lf-.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSES/BSD-2-Clause.txt","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2020-07-16T08:49:20.000Z","updated_at":"2025-06-18T02:11:16.000Z","dependencies_parsed_at":"2023-11-30T00:23:57.892Z","dependency_job_id":"739c7a06-a9dc-4585-89ff-c336050a4642","html_url":"https://github.com/lf-/nix-doc","commit_stats":{"total_commits":54,"total_committers":3,"mean_commits":18.0,"dds":0.4814814814814815,"last_synced_commit":"07bbba3c27aac53261770380f3e369787bcc365c"},"previous_names":[],"tags_count":23,"template":false,"template_full_name":null,"purl":"pkg:github/lf-/nix-doc","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lf-%2Fnix-doc","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lf-%2Fnix-doc/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lf-%2Fnix-doc/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lf-%2Fnix-doc/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/lf-","download_url":"https://codeload.github.com/lf-/nix-doc/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lf-%2Fnix-doc/sbom","scorecard":{"id":586717,"data":{"date":"2025-08-11","repo":{"name":"github.com/lf-/nix-doc","commit":"55599ec502e01e96673cbfcd2940b9dc1d392ec5"},"scorecard":{"version":"v5.2.1-40-gf6ed084d","commit":"f6ed084d17c9236477efd66e5b258b9d4cc7b389"},"score":2,"checks":[{"name":"Code-Review","score":0,"reason":"Found 1/29 approved changesets -- score normalized to 0","details":null,"documentation":{"short":"Determines if the project requires human code review before pull requests (aka merge requests) are merged.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#code-review"}},{"name":"Dangerous-Workflow","score":-1,"reason":"no workflows found","details":null,"documentation":{"short":"Determines if the project's GitHub Action workflows avoid dangerous patterns.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#dangerous-workflow"}},{"name":"Token-Permissions","score":-1,"reason":"No tokens found","details":null,"documentation":{"short":"Determines if the project's workflows follow the principle of least privilege.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#token-permissions"}},{"name":"Packaging","score":-1,"reason":"packaging workflow not detected","details":["Warn: no GitHub/GitLab publishing workflow detected."],"documentation":{"short":"Determines if the project is published as a package that others can easily download, install, easily update, and uninstall.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#packaging"}},{"name":"Binary-Artifacts","score":10,"reason":"no binaries found in the repo","details":null,"documentation":{"short":"Determines if the project has generated executable (binary) artifacts in the source repository.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#binary-artifacts"}},{"name":"Maintained","score":0,"reason":"0 commit(s) and 0 issue activity found in the last 90 days -- score normalized to 0","details":null,"documentation":{"short":"Determines if the project is \"actively maintained\".","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#maintained"}},{"name":"Pinned-Dependencies","score":-1,"reason":"no dependencies found","details":null,"documentation":{"short":"Determines if the project has declared and pinned the dependencies of its build process.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#pinned-dependencies"}},{"name":"CII-Best-Practices","score":0,"reason":"no effort to earn an OpenSSF best practices badge detected","details":null,"documentation":{"short":"Determines if the project has an OpenSSF (formerly CII) Best Practices Badge.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#cii-best-practices"}},{"name":"Security-Policy","score":0,"reason":"security policy file not detected","details":["Warn: no security policy file detected","Warn: no security file to analyze","Warn: no security file to analyze","Warn: no security file to analyze"],"documentation":{"short":"Determines if the project has published a security policy.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#security-policy"}},{"name":"License","score":9,"reason":"license file detected","details":["Info: project has a license file: Cargo.lock.license:0","Warn: project license file does not contain an FSF or OSI license."],"documentation":{"short":"Determines if the project has defined a license.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#license"}},{"name":"Fuzzing","score":0,"reason":"project is not fuzzed","details":["Warn: no fuzzer integrations found"],"documentation":{"short":"Determines if the project uses fuzzing.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#fuzzing"}},{"name":"Signed-Releases","score":-1,"reason":"no releases found","details":null,"documentation":{"short":"Determines if the project cryptographically signs release artifacts.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#signed-releases"}},{"name":"Branch-Protection","score":0,"reason":"branch protection not enabled on development/release branches","details":["Warn: branch protection not enabled for branch 'main'"],"documentation":{"short":"Determines if the default and release branches are protected with GitHub's branch protection settings.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#branch-protection"}},{"name":"SAST","score":0,"reason":"SAST tool is not run on all commits -- score normalized to 0","details":["Warn: 0 commits out of 2 are checked with a SAST tool"],"documentation":{"short":"Determines if the project uses static code analysis.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#sast"}},{"name":"Vulnerabilities","score":2,"reason":"8 existing vulnerabilities detected","details":["Warn: Project is vulnerable to: RUSTSEC-2021-0139","Warn: Project is vulnerable to: RUSTSEC-2021-0145 / GHSA-g98v-hv3f-hcfr","Warn: Project is vulnerable to: RUSTSEC-2024-0375","Warn: Project is vulnerable to: RUSTSEC-2024-0384","Warn: Project is vulnerable to: RUSTSEC-2024-0370","Warn: Project is vulnerable to: RUSTSEC-2022-0013 / GHSA-m5pq-gvj9-9vr8","Warn: Project is vulnerable to: RUSTSEC-2023-0018 / GHSA-mc8h-8q98-g5hr","Warn: Project is vulnerable to: RUSTSEC-2022-0006 / GHSA-9hpw-r23r-xgm5"],"documentation":{"short":"Determines if the project has open, known unfixed vulnerabilities.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#vulnerabilities"}}]},"last_synced_at":"2025-08-20T20:42:10.936Z","repository_id":37680051,"created_at":"2025-08-20T20:42:10.937Z","updated_at":"2025-08-20T20:42:10.937Z"},"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":274475969,"owners_count":25292523,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-09-10T02:00:12.551Z","response_time":83,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["nix","nix-plugin"],"created_at":"2024-08-02T13:01:49.900Z","updated_at":"2025-09-10T14:10:30.763Z","avatar_url":"https://github.com/lf-.png","language":"Rust","funding_links":[],"categories":["Rust"],"sub_categories":[],"readme":"\u003c!-- SPDX-License-Identifier: LGPL-3.0-only --\u003e\n\u003c!-- SPDX-FileCopyrightText: 2024 Jade Lovelace, 2022 tdro --\u003e\n\n# nix-doc\n\nA Nix developer tool leveraging the `rnix` Nix parser for intelligent\ndocumentation search and tags generation.\n\n## Features\n\n* Nix plugin that adds a builtin that can display the signature and\n  documentation for a lambda object in a friendly format\n* Command line tool that searches Nix files in a directory for functions and\n  shows documentation for matching ones\n* Tags generator similar to `ctags` that can generate a vim compatible tags\n  file for Nix source\n* High performance, threaded implementation in Rust\n\n## Setup\n\n```\n# nix-doc is in nixpkgs\n$ nix-env -i nix-doc\n\n# you can alternatively get it from git\n$ nix-env -i -f https://github.com/lf-/nix-doc/archive/main.tar.gz\n\n# or if you don't want to use nix (only includes the command line tool for\n# search and tags)\n$ cargo install --locked nix-doc\n```\n\n### Nix Plugin\n\nTo install the Nix plugin on a single-user installation of Nix, add this to\nyour Nix config at `~/.config/nix/nix.conf` after installing `nix-doc` with\n`nix-env`:\n\n```\nplugin-files = /home/YOURUSERNAMEHERE/.nix-profile/lib/libnix_doc_plugin.so\n```\n\nFor a multi-user installation, you will need to do something like this:\n\n```\n$ sudo ln -s $(nix-build '\u003cnixpkgs\u003e' -A nix-doc) /opt/nix-doc\n```\n\nand then put this into your `/etc/nix/nix.conf`:\n\n```\nplugin-files = /opt/nix-doc/lib/libnix_doc_plugin.so\n```\n\n## NixOS Installation\n\nLink the plugin file using\n`nix.extraOptions`:\n\n```nix\n{ pkgs, ... }:\n\n{\n  nix.extraOptions = ''\n    plugin-files = ${pkgs.nix-doc}/lib/libnix_doc_plugin.so\n  '';\n\n  environment.systemPackages = with pkgs; [\n    nix-doc\n  ];\n}\n```\n\n\n## Usage\n\n### CLI\n\n```\nnix-doc \u003ccommand\u003e\n```\n\n#### `nix-doc tags [dir]`\n\nGenerates a vim-compatible `tags` file in the current directory, for all nix\nscript files below the directory `dir`.\n\nExample:\n\n```\nnixpkgs$ nix-doc tags\n\nnixpkgs$ file tags\ntags: Exuberant Ctags tag file, ASCII text, with very long lines (502)\n\n# opens vim to the function callCabal2nix\nnixpkgs$ vim -t callCabal2nix\n```\n\n#### `nix-doc search \u003cregex\u003e [dir]`\n\nExample output:\n\n```\nnixpkgs$ nix-doc search callPackage\n   Call the package function in the file `fn' with the required\n   arguments automatically.  The function is called with the\n   arguments `args', but any missing arguments are obtained from\n   `autoArgs'.  This function is intended to be partially\n   parameterised, e.g.,\n\n   callPackage = callPackageWith pkgs;\n   pkgs = {\n   libfoo = callPackage ./foo.nix { };\n   libbar = callPackage ./bar.nix { };\n   };\n\n   If the `libbar' function expects an argument named `libfoo', it is\n   automatically passed as an argument.  Overrides or missing\n   arguments can be supplied in `args', e.g.\n\n   libbar = callPackage ./bar.nix {\n   libfoo = null;\n   enableX11 = true;\n   };\ncallPackageWith = autoArgs: fn: args: ...\n# ./lib/customisation.nix:117\n─────────────────────────────────────────────\n   Like callPackage, but for a function that returns an attribute\n   set of derivations. The override function is added to the\n   individual attributes.\ncallPackagesWith = autoArgs: fn: args: ...\n# ./lib/customisation.nix:127\n─────────────────────────────────────────────\n   Similar to callPackageWith/callPackage, but without makeOverridable\ncallPackageWith = autoArgs: fn: args: ...\n# ./pkgs/development/beam-modules/lib.nix:7\n```\n\n### Nix plugin\n\nThe Nix plugin provides three builtins:\n\n#### `builtins.doc f`\n\nPrints the documentation of the function `f` to the screen. Returns `null`.\n\n#### `builtins.getDoc f`\n\nReturns the documentation message for the function `f` as a string (exactly the\nsame output as `builtins.doc`, just as a string).\n\n#### `builtins.unsafeGetLambdaPos`\n\nA backport of [NixOS/Nix#3912](https://github.com/NixOS/nix/pull/3912). Returns\nthe position of a lambda, in a similar fashion to `unsafeGetAttrPos` for\nattributes.\n\n#### Sample usage:\n\n```\n» nix repl\nWelcome to Nix version 2.3.7. Type :? for help.\n\nnix-repl\u003e n=import \u003cnixpkgs\u003e {}\n\nnix-repl\u003e builtins.doc n.lib.callPackageWith\n   Call the package function in the file `fn' with the required\n   arguments automatically.  The function is called with the\n   arguments `args', but any missing arguments are obtained from\n   `autoArgs'.  This function is intended to be partially\n   parameterised, e.g.,\n\n     callPackage = callPackageWith pkgs;\n     pkgs = {\n       libfoo = callPackage ./foo.nix { };\n       libbar = callPackage ./bar.nix { };\n     };\n\n   If the `libbar' function expects an argument named `libfoo', it is\n   automatically passed as an argument.  Overrides or missing\n   arguments can be supplied in `args', e.g.\n\n     libbar = callPackage ./bar.nix {\n       libfoo = null;\n       enableX11 = true;\n     };\nfunc = autoArgs: fn: args: ...\n# /nix/store/frpij1x0ihnyc4r5f7v0zxwpslkq6s27-nixpkgs-20.09pre237807.0dc87c6e54f/nixpkgs/lib/customisation.nix:117\nnull\n```\n\n## Development\n\nThis repository is set up as a Cargo workspace with the plugin and the command\nline tool/library as parts.\n\nIt is not really possible to build the plugin outside a Nix shell since Nix\ndoes not provide libraries outside the shell environment. As such, it is\nsuggested to use a nix shell while developing the plugin as follows:\n\n```\n$ nix-shell\n[nix-shell]$ cargo build\n[nix-shell]$ cargo check\n[nix-shell]$ cargo test\n# etc\n```\n\n## TODO\n\n- Tech: should update rnix to the latest major.\n\n## Related work\n\n- https://github.com/NixOS/nix/pull/1652: A PR implementing basically the same\n  thing as this tool's plugin in Nix itself, which has been deferred\n  indefinitely due to disagreements about what syntax to use in documentation\n  comments.\n- https://github.com/tazjin/nixdoc: A Rust tool producing DocBook documentation\n  for Nix library functions.\n- https://github.com/mlvzk/manix: An early fork of this tool with a stronger\n  focus on CLI usage, with support for indexing and faster search. By\n  comparison, their CLI is better, but they don't do tags or a Nix plugin.\n\n## Project information\n\nEveryone is expected to follow the [code of conduct](./CODE_OF_CONDUCT.md)\nwhile participating in this project.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flf-%2Fnix-doc","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Flf-%2Fnix-doc","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flf-%2Fnix-doc/lists"}