Closed hsjobeki closed 5 months ago
Nice! We should definitely wait for the RFC to be accepted, which should be pretty soon. After that I'm generally in favor of merging it, but we definitely need tests, documentation and a changelog entry for this.
This pull request has been mentioned on NixOS Discourse. There might be relevant details there:
https://discourse.nixos.org/t/2024-01-04-documentation-team-meeting-notes-102/37754/1
@infinisil could i ask you for some review & suggestions?
Nice, I've been eagerly awaiting a ping for it to be ready :D. I can't get to it immediately, but I'll take a close look when I get to it!
This pull request has been mentioned on NixOS Discourse. There might be relevant details there:
https://discourse.nixos.org/t/2024-02-15-documentation-team-meeting-notes-109/39826/1
This pull request has been mentioned on NixOS Discourse. There might be relevant details there:
https://discourse.nixos.org/t/tweag-nix-dev-update-54/39990/1
@infinisil. Just worked your feedback in.
@infinisil to keep you updated. I just bootstrapped a cli tool https://github.com/hsjobeki/flutsch. Which in combination with a static analysis tool could replace nixdoc entirely.
Features such as #98 make more sense on nix value level. Unfortunately the comments are not part of the c++nix ast which requires invoking an addtional (e.g. rnix based) tool.
Just some minor bits now
I just bootstrapped a cli tool https://github.com/hsjobeki/flutsch. Which in combination with a static analysis tool could replace nixdoc entirely.
Nice! I generally don't mind archiving nixdoc if there's something better. Though I definitely can't say I'm a fan of C++ 😅
Yes. C++ is horrible. My vision is to use it only for the information that we need to pull out of the native evaluator. (Using rust with the tvix evaluator would be a nice alternative but we wouldn't want nixpkgs docs to depend on tvix^^)
Then using a static rust/rnix based tool on top of that (introspection information) to generate the markdown docs.
@infinisil
Adds support for doc-comments. (see: https://github.com/nixos/rfcs/pull/145)
onetwo levels, so the nixpkgs manual rendering still works.Doesn't discover new items, it just renders, what was rendered before. (e.g. lib.lists.map keeps name and section heading) But If the content is a new doc-comment (surrounded by
/** */
) then it doesn't perform the 'nixdoc' rendering withExample:
andType:
sections. Instead the section headings are written in explicit markdown by the user/documentation writer. All section headings are automatically shifted down two levels. (Means you can and should currently write H1 to H4 in your doc comments)This is certainly a limitation, to resolve this we need to change the nixpkgs manual rendering tool (nixos_render_docs) which could be one of the next steps.
Moved some rust functions into separate files. Having everything in main.rs makes it hard to maintain two separate feature sets.
legacy.rs
format.rs
test.rs
Version 3.0.0
This PR bumps the version to 3.0.0