Sphinx support for Nix?

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.

7 Likes

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?

I’ll be very interested by this. Also even though I have no prior experience with discussions taken about docs in Nix projects, I support the idea of making a Sphinx extension since apart from the fact it’s a great tool, the extension has to be written using the same language as NixOps (:snake:) so it doesn’t put a language barrier.

Don’t hesitate if you need contributions / help on the extension.

I pretty much have foregone trying to find documentation for stuff, I just use ripgrep to find where things are defined. It would have been nice to have better documentation when I was getting my feet wet.

I like the haskell flavored markdown.

The proper way to go about this would probably be to initiate an RFC, so that there can be consensus about the direction of this and move forward as a community

cc @worldofpeace because rfc involvement

2 Likes

I believe there’s a lot of volunteers and contact points for improving documentation in Nix.
However, I’m not currently one of those contact points. And TBH, I avoid it entirely :rofl:

I do support @parkerhoyes in finding a way to contribute to the documentation tooling.
This is currently what I think makes our current docs setup difficult in even general use.

Having a Nix domain for Sphinx is I think very useful. Maybe not in Nixpkgs though (that’s a bigger, separate discussion), because lib is already formatted and parsed in a certain way.
https://github.com/NixOS/nixpkgs/pull/53055