search

nix-community / nixdoc

Tool to generate documentation for Nix library functions [maintainer=@infinisil]
GNU General Public License v3.0
122 stars 14 forks source link

render structured arguments without subheadings #35

Closed pennae closed 1 year ago

pennae commented 1 year ago

nixos-render-docs requires IDs on all headings to guarantee stable links. this is mostly the case already, except in breakdowns of structured arguments.

render pattern arguments as deflist entries, just like normal arguments, and nest their contained attrs in an inner deflist.

pennae commented 1 year ago

Is this something that would look different on the nixpkgs manual?

probably. nested deflists seem to render fine in the nixpkgs, but we haven't tested this generator specifically against the nixpkgs manual rendering process. we have tested it against nixos-render-docs, and it did work fine there.

Weird HTML?

possibly related to why your deflists don't nest properly. haven't looked into it that deeply, but we haven't been able to reproduce anything like that in the manual so far. instead of multiple dd tags we get one with multiple p tags nested inside, as we'd expect

asymmetric commented 1 year ago

Apologies for the delay, I can confirm that the weirdness in rendering happened because I wasn't passing the required flags to pandoc.

Calling this with

pandoc -f commonmark+attributes+fenced_divs+footnotes+bracketed_spans+definition_lists+pipe_tables+raw_attribute+smart

as is done for the nixpkgs manual, produces correct HTML.