search

nix-community / nixdoc

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

feat: Support descriptions from comments #70

Closed phaer closed 1 year ago

phaer commented 1 year ago

This extends the existing --description flag with two options:

This is the most minimal implementation providing the features I was looking for. Happy to extend it w.r.t. to white-space handling and ideally getting section link anchors back for included headers; which would require us to parse the input.

phaer commented 1 year ago

Thanks for the feedback! Just pushed a version with separate flags. Let me know if should remove ´--description-file´

phaer commented 1 year ago

Furthermore, not having any description at all makes it fail: This is in contrast to the current nixdoc which always falls back to something sane in case of > missing data. And in this case the default should obviously be an empty description.

The behavior you describe happens only if you explicitly pass the flag. Without that flag, there's no change to behavior. I think its preferable to raise an error if the flag is passed and there's no comment, seems less surprising than silently ignoring the flag.

Also the flag should be renamed. --description-extract sounds like it would be related to the --description flag, when it doesn't really seem to be.

Could you elaborate on this? How would you call the extracted text here and what would be the difference to a ?description"?

I'd also be in favor of just not having a flag for this at all though, this seems like sane default behavior.

Happy to do this, but as @asymmetric disliked expanding an existing flag for backwards-compatibility, I assumed changing default behavior would be even less likely to get merged ;)

Happy to continue with this. Another open question we've discussed at NixCon was whether it's deemed worth the effort to parse and re-serialize the descriptions in order to insert anchors to headings. I think it's fair to leave that functionality to the actual renderers, as i.e. Github and mdbook support that by themselves.

infinisil commented 1 year ago

Happy to do this, but as @asymmetric disliked expanding an existing flag for backwards-compatibility, I assumed changing default behavior would be even less likely to get merged ;)

I don't think this would be a problem for Nixpkgs. If at all, header comments in lib functions either are inexistent or describe the sublibrary, which is what we want. So this would be my preference. Because of nixdoc's state of mainly being used for Nixpkgs and being fairly ad-hoc, I don't think we need to have strong backwards-compatibility guarantees.

nixos-discourse commented 1 year ago

This pull request has been mentioned on NixOS Discourse. There might be relevant details there:

https://discourse.nixos.org/t/2023-11-09-documentation-team-meeting-notes-93/35244/1

phaer commented 1 year ago

@infinisil Seeing you became the new maintainer of nixdoc - thanks! :tada: - I don't think we need additional feedback to make it a default behavior. Let me know what you think! :)

phaer commented 1 year ago

Not sure how long-lived nixdoc will still be with RFC 145, but let's keep it working!

If I read it correctly, RFC 145 doesn't say anything about a tool to render markdown/html documentation and neither do the linked PoCs. Am I missing something here? As stated above my primary motivation is code that lives outside of nixpkgs.

infinisil commented 1 year ago

Ah that's true. I kind of assumed that the RFC 145 shepherd team was working on their own tooling to replace this one. I created https://github.com/nix-community/nixdoc/issues/90 to discuss this.

my primary motivation is code that lives outside of nixpkgs.

Haven't considered this very thoroughly, but I guess that's a valid use case, so let's continue supporting it :)