nix-community / docnix

nix-community reference documentation (until officially released) [maintainer=@hsjobeki]

Docnix

Finally, complete autogenerated documentation for the whole nix-ecosystem.

View here

🚧🚧🚧 Under Construction 🚧🚧🚧

Content

Autogenerated documentation from source code including

• lib.*
• pkgs.*
  • pkgs.stdenv.*
• builtins.*

How it works

0. Preparation

For this to work properly we need doc-comments in format according to RFC-145. Since nixpkgs is not entirely written in this format we use our package codemod to automatically migrate all comments.

Nixpkgs -> Nixpkgs'

1. Data extraction

The next step is calling our custom builtins unsafeGetAttrDoc and unsafeGetLambdaDoc to retrieve the documentation for all functions in the nixpkgs expression tree.

Nixpkgs' -> json

2. Data separation / aggregation

Data is scanned, and additional information from positions, partially applied aliases, etc. is collected and dumped into separate markdown files. Every markdown file also includes a short yaml header needed by the rendering framework.

It contains information about the navigation, tags, headlines and other meta information.

Json -> Markdown

3. Rendering

We then utilize a simple javascript rendering framework to transform all the scraped data into separate markdown / html pages.

A search index and sitemap.xml is built for page search as well as for external search engines like Google.

Markdown -> Static html

Et voila 🥳

Contributing / Remaining work

All contributions are welcome! ❤️

• We still need the RFC-145 to be accepted. 👍
• review all the nixpkgs doc-comments changes. 👀
  • This draft PR#262987 should be split into multiple PRs, reviewed manually and merged. 🔪
• Change the current nixpkgs manual rendering as it will break when using plain markdown in nixpkgs comments. 😱
• Clarify rendering rules / best practices ☝️
  • for aliased functions.
  • for builtins
• Writing more doc-comments ⌨ ✍️
  • lib. types and options are almost completely undocumented
  • pkgs.stdenv is missing some documented functions

docnix's Issues

Some functions missing from the list

I'm missing some functions like pkgs.buildEnv or pkgs.dockerTools.buildLayeredImage. Noogle is missing those as well. Maybe the logic for finding functions needs to be improved?

Search orders results confusingly

See this example:

I am searching for "optionals", and there is lib.optionals that matches this search exactly, but it is not the first result or even on the first page.

Dependency Dashboard

This issue lists Renovate updates and detected dependencies. Read the Dependency Dashboard docs to learn more.

Open

These updates have all been created already. Click a checkbox below to force a retry/rebase of any.

• Update all dependencies (@astrojs/starlight, actions/deploy-pages, actions/upload-pages-artifact, astro, cachix/cachix-action, cachix/install-nix-action, expect-test, pagefind, regex, rowan, textwrap, walkdir)
• Lock file maintenance

Detected dependencies

cargo

codemod/Cargo.toml

• regex 1.9.5
• rnix 0.11.0
• rowan *
• textwrap 0.16.0
• walkdir 2.4.0
• expect-test 1.4.0

github-actions

.github/workflows/deploy.yml

• actions/checkout v4
• cachix/install-nix-action v23
• cachix/cachix-action v12
• actions/upload-pages-artifact v2
• actions/deploy-pages v2

nix

flake.nix

• nixpkgs nixpkgs-unstable

npm

packages/static-docs/package.json

• @astrojs/starlight ^0.12.0
• astro ^3.0.6
• pagefind ^1.0.3

---

• Check this box to trigger a request for Renovate to run again on this repository

The Github icon at the top points to nixpkgs, not this repo

The Github icon in the header points to nixpkgs right now.

I would expect it to point at this repo here. It's not a huge issue at this moment because it's easy to deduct the repo location from the URL of the site (https://nix-community.github.io/docnix/), but at first this made me think that this was already part of nixpkgs somehow.

"Contribute Now!" often link to wrong location

The "Contribute Now!" links seem to often not point at the correct location. See wrapNeovim, hunspellWithDicts or libcCrossChooser for wrong links and overrideCC, generateSplicesForMkScope and extend for correct links.

Reference is down?

The following URL was working, now is 404

https://nix-community.github.io/docnix/reference/

Link to code definition

Hi, I stumbled across the reference page the other day and am quite impressed.

With the best documentation it can be quite helpful to read code, and especially helpful if the documentation is not as good. I'm wondering if it would be possible to link back to the code definitions?

Find a better name for the project

I think the name docnix is too generic and confusing as there are other projects with a similar name (e.g. nix-doc).