Giters

lf- / nix-doc

An interactive Nix documentation tool providing a CLI for function search, a Nix plugin for docs in the REPL, and a ctags implementation for Nix script

Geek Repo:Geek Repo

Github PK Tool:Github PK Tool

Suggested pipeline for HTML output?

mikepurvis opened this issue · comments

commented

I'm looking to generate HTML output for Nix function comment docs, and although it doesn't look like this project does that natively, I'm wondering if it could be a piece of the puzzle, specifically:

  1. nix-doc processes nix sources into ctags files
  2. ctags files are transformed into rST documents
  3. a manual written in rST can include per-function documentation
  4. Sphinx transforms the rST into HTML output

Alternatively, perhaps this is a silly amount of indirection and it would make more sense to start a new project that leverages rnix-parser directly to either generate HTML output or generate intermediate text files for something like Sphinx to consume.

Has anyone explored these directions at all?

commented

Hi! An amusingly similarly named project has done this already: https://github.com/nix-community/nixdoc

If you wanted to leverage nix-doc you could use builtins.getDoc, or you could do the extraction in pure Nix: https://puck.moe/git/zilch/tree/lib/package/comments.nix. Regardless, this is outside the scope of nix-doc :) feel free to reuse some code though, it's LGPL.

commented

Ahh yes, I did look briefly at that, but kind of dismissed it out of hand on account of being five years old and a prototype— however, it's absolutely exploring the space I'm describing, so it may well be a good starting point. Thanks for the pointer!