docnix

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

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