Skip to content
This repository has been archived by the owner on Jul 3, 2024. It is now read-only.
/ docnix Public archive

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

Notifications You must be signed in to change notification settings

nix-community/docnix

Repository files navigation

Docnix

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

🚧🚧🚧 Under Construction 🚧🚧🚧

Content

Autogenerated documentation from source code including

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

How it works

  1. 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

  1. 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

  1. 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