What is the Doxygen of Nix?

It looks like most of the current documentation for the Nix projects is written as separate, parallel manuals, eg:

This is per the guidelines laid out in rfcs/0072-commonmark-docs.md at 71f76fab15d2d6c3b86ae2814c6d7adef8f59d75 · NixOS/rfcs · GitHub

But I do note that some files in nixpkgs have docblocks that look like they could well be extracted and rendered into documentation similar to how Doxygen or Sphinx works:

This could be as sophisticated as something like rnix-parser, or as naive as some regular expressions. Has there been any effort made to bridge this gap, and build a doc-extractor for a Nix codebase, that could render out the documented functions to markdown or rST pages, for example for inclusion in a Sphinx-based manual?

I’m interested in this topic in general, but also specifically with respect to Nix code related to packaging ROS (Robot Operating System), for example: nix-ros-base/build-colcon-package.nix at 76f97d373d1c61d48df146dbd42df8202a9ff1fe · clearpathrobotics/nix-ros-base · GitHub

I don’t think I have the resources to maintain a fully separate manual for this codebase, but it sure would be helpful to be able to at least extract properly formatted comments.


There is nixdoc, which is used for generating the documentation for the lib functions of Nixpkgs and is used by the Nixpkgs manual.

Nix does not really enforce any structure like some other languages so any tool will have to be code base specific. Maybe something like std can bring that in the future.


Related: How to generate documentation from arbitrary nix code?
@mightyiam maybe you may want to get in touch with each other to collaborate?


Thank you, @fricklerhandwerk . If anyone is interested in joining me in collaborating on this in mob programming format, please message me.