Very nice! I have a personal preference for Sphinx, but regardless I think this is very good to have and we should get this in. I wonder though what others think of changing the format of the docstrings.

(I added the python tag to check a hypothesis w.r.t. the incorrect label added by ofborg. I'll remove it shortly, sorry for the noise)

@GrahamcOfBorg eval

I had thought about this long ago, but I didn't realize it could work to use a different language ❤️

Sphinx takes data via doxygen, at least in projects I know about.

@FRidh I totally agree! Sphinx definitely has a nicer looking theme by default. Doxygen lets you create a custom template, so I was thinking of mimicking the NixOS.org styling. I've got the header on the demo page here.

@vcunat Sort of a happy accident that it works since Doxygen is in c++ mode. Other modes may work better, although the "best" would be to write a Nix language definition. Glad you like it!

Sphinx takes data via doxygen, at least in projects I know about.

Right. That's still an option then.

@lukeadams could you look how to integrate this in the Nixpkgs manual? Doxygen supports docbook output. http://doxygen.nl/manual/config.html#cfg_generate_docbook

When we have that available, we could consider looking further than just lib, like also the trivial-builders and shell scripts like makeWrapper.

@FRidh With that option enabled, I just have to add Doxygen generation to doc/default.nix and tell the docstring builder to look at its output.

I've now labelled strings.nix as a member of lib so it shows up here. All functions in other files will show up there as long as they are marked as members of lib. I'm not sure how to get Doxygen to generate docs from .sh files, but it would be trivial to create a markdown file for each one and document it that way

(Sorta) got it linked into the manual here.

Needs some massaging to make it look good though.

I've been looking for such documentation and happy that someone finally commits to writing it.
All Nixpkgs builtin functions should have clear API documentation reference like standard libraries in other languages, specifying type of arguments, type of return, usage example. Syntax highlight would be nice.
Will appreciate to see project alive and completed, even if it will not be merged yet to master.

@oxij I'll look into it! Doxygen was just for proof of concept since I was already familiar with it.
I agree – Javadoc is obscenely verbose (but works well when using non D-gen supported languages for the same reason).

Oh yeah not sure if you noticed but in many cases I had to wrap lib code with /** @cond EXCLUDE */ as Doxygen would get confused by the syntax, which adds a source of potential document breakage if changes are made to lib functions. The whole thing is messy.

@FRidh Honestly I think Sphinx would be the best option with a custom domain (link up top) which would add Nix support to it. Additionally, the inbuilt sphinx.Napoleon extension supports a docstring style similar to what we already have in-tree. Doxygen requires too much hacking to work reliably and its Docbook output requires quite a bit of massaging to embed in the manual.

Thoughts?

I'm going to close this as I no longer have the time to work on it.
May pursue it in the future by using the Nix Lex/Yacc {see parser.y, lexer.l} parser to write a frontend for Sphinx, or maybe create a standalone tool "NixDoc" in the same vein as rustdoc