In reply to @sternenseemann:systemli.org
do we have an overview of what markdown extensions/custom stuff you can use in the manual somewhere?

In reply to @sternenseemann:systemli.org
do we have an overview of what markdown extensions/custom stuff you can use in the manual somewhere?

Dynamically determining docs has a lot of problems: What constitutes the doc comment? The comment at the let binding? At the inherit exposing it? What happens if I pass the value through the identity function? etc. pp. This is because we don't have a sense of an exported symbol. Consequently we need to establish some sort of convention here that can be transferable to static doc generation since every file has to be a full Nix expression.

When dynamically gathering documentation you don't suddenly have no issues: You need to know about the library's structure, e.g. which of the exposed functions are aliases? which functions are deprecated? Since you can't know this. The whole story becomes a lot worse if you are not dealing with anything as tame as <nixpkgs/lib>. E.g. haskellPackages exposes some functions (callCabal2nix, …) that should be documented, but here treewalking becomes difficult, a lot of dynamicism is involved, you need to know what to ignore etc. (heck, the functions exposed could differ depending on platform or the like). In short, dynamically gathering docs is not a silver bullet.

When statically doing docs, you need to have a convention, yes, and need to somehow be able to tell it how it relates to the “library” as a whole. This also requires special knowledge about the library, but so does the dynamic solution.

This is my point: Both solutions suffer from variations of the same problem; and the problem is that we have no module system, so a library could be structured in arbitrary ways and it is impossible to figure out what's what independently of the concrete code.

Hey, will miss this meeting too unfortunately, sorry for the streak of no-shows, hopefully should end in the next couple of weeks.

The little work I’ve done was reviewing nixdoc. I’ll get to my open PRs on nix.dev asap, but if I’m a blocker, feel free to use your best judgement and merge ahead.

See you soon!

In reply to @asymmetric:matrix.dapp.org.uk
Hey, will miss this meeting too unfortunately, sorry for the streak of no-shows, hopefully should end in the next couple of weeks.
The little work I’ve done was reviewing nixdoc PRs. I’ll get to my open PRs on nix.dev asap, but if I’m a blocker, feel free to use your best judgement and merge ahead.
See you soon!

And again, thanks everyone on the docs and learning journey team. It doesn’t always feel like it on the inside, and it’s not always visible on the outside, but we have taken up enormous momentum. While we’re still have many discussions around finding the right approach and aligning our views, all of you are getting awesome things done, and we’re clearly transitioning into the “performing” phase.

The last few sessions in particular were extraordinarily productive. We’re doing reviews, make decisions, merge changes, and I see a lot of major improvements for user and contributor experience on the horizon.

Don’t get me wrong, it will still take months until everything gets noticeably smoother. But I’m genuinely amazed how we managed to get rolling with a couple of hours a week from everyone.