I’ve only just started experimenting with Nix recently but so far I’ve enjoyed how expressive and powerful the build system can be.
One thing I have not enjoyed however is the lack of documentation in certain areas, especially the various APIs in nixpkgs. I know there has been lots of discussion about how Nix documentation should work and that there has been some work done at documenting the nixpkgs APIs using various tools, but as far as I’m aware there’s a lack of overall consensus about how this should be done.
I’d like to help out, but I certainly don’t have the knowledge or the free time to add to the existing documentation for nixpkgs. However, I can help by improving the documentation tooling. From reading through the forums I got the impression that the reason there’s no single Nix doc tool which is being widely used is because there’s no tool which:
- Has support for Nix specifically
- Can autogenerate documentation from comments in source code
- Supports a format that’s widely used (eg. Markdown or reST)
I have experience with Sphinx, and specifically with writing extensions for Sphinx, so I could add support for a custom Nix domain. This would allow us to completely customize the documentation syntax to suit our needs, and we would inherit all of the benefits of Sphinx (cross-references, easy to read reST markup, etc.).
For example, here’s what some documentation might look like:
/*
* fetchGit :: url -> repo
* fetchGit :: { url, name, rev, ref } -> repo
*
* Fetch a git repo from ``url``. Also see :func:`builtins.fetchurl`.
*
* :value url string: The source URL
* ...
* :value repo path: The path to the git repo in the Nix store
* :aborts: If there's an error downloading
*/
fetchGit = ...
Or, alternatively:
/*
* fetchGit = url (string): repo (path)
* fetchGit = args@{ url (string), name (string), rev (string), ref (string) }: repo (path)
* ...
*/
fetchGit = ...
Even more possibilities:
/*
* .. nix:value:: myFunctor :: { someString :: string, someList :: [int], ... }
* :callable:
*
* A set that's callable. Neat!
*
* .. example::
* ...
* .. warning:: ...
*/
myFunctor = { __functor = ...; ... };
You get the point: there’s room for customization. We’d have to make some decisions about what syntax to use.
Whatever we decide, it would be easy to compile the documentation to HTML so it can be hosted on ReadTheDocs or NixOS.org or whatever.
Thoughts? Has anybody tried to make a Sphinx extension for Nix? Is this something people would be interested in using, or would my work be in vain?
Edit: I think it’s also worth pointing out that Sphinx supports both reST and Markdown, though you’d have to use reST to be able to use cross-references and such. Nonetheless, you could write tutorials in Markdown and reference manuals in reST and Sphinx could compile them all into the same place.
) so it doesn’t put a language barrier.