Open hsjobeki opened 5 months ago
This pull request has been mentioned on NixOS Discourse. There might be relevant details there:
https://discourse.nixos.org/t/2024-03-21-documentation-team-meeting-notes-114/41957/1
@infinisil I think this PR is ready from my side. If you could give it a quick revise, if all issues are addressed.
Just tested it against nixpkgs with some lib functions. works really nice, didn't notice any problems or issues with the other tooling whatsoever.
Note: I switched to another frontmatter parser library because the error handling wasn't expressive enough.
Reviewed in the docs team meeting:
doc-location
mean?(PS: @hsjobeki and @DanielSidhion your effort to improve reference documentation overall is highly laudable, so my critique of this particular pattern is not to dismiss your work.)
When the pattern is used, it's proliferated over time, and I fear it will add friction below the threshold of pain.
@fricklerhandwerk @infinisil.
This fear is justified, and I share it. Nevertheless, it would be very beneficial to provide this feature for individual edge cases with very long documentation. This should not be used extensively, and there are only a handful of places where I can imagine this. For example, the "mkDerivation" function documentation is rather extensive, and you wouldn't want that in the source code.
So nixdoc is just a documentation tool that offers this feature. It is not an official tool or an opinionated tool. But nixpkgs should adhere to usage guidelines. e.g. to use the doc_location feature only for certain functions.
I am still demanding this feature and planning to add more features to "frontmatter" later on, which might be needed in my vision for improved documentation.
But i am okay to let this PR stay open until we really need it. (e.g. when we can generate documentation for mkDerviation)
This pull request has been mentioned on NixOS Discourse. There might be relevant details there:
https://discourse.nixos.org/t/2024-03-28-documentation-team-meeting-notes-115/42329/1
Add support for frontmatter
Why frontmatter is needed (sometimes)
Sometimes it is desireable to extend the content with meta information. Frontmatter is the de-facto standard of adding document specific meta tags to markdown. 1 2 3
This would allow us to keep track of references between documents that are closely related to nix code or externalized doc-comments that are no longer tracked.
This PR also includes a detailed design document.
i.e.,
Example
TODO