Checking which modules are in the works

[FluxZA]

Is there a place to say "I am creating a module for program x"? I want to create a zsh module, but don't want to recreate the wheel.

As an aside, this idea is really cool, and exactly what I have been looking for to use programs inside dev containers. Thanks for working on it and let me know if there is a way to help outside of contributing new wrapper modules.

[BirdeeHub]

Well, theres no wheel for that one yet so go for it!

I have this thing which is not a module but it builds a ZDOTDIR in my config, it seems to work, not 100% confident in it Some of the modules in my config could use some updates and/or are unfinished so don't take anything in there as gospel lol but that thing I linked does what I said it does at least XD Most of the stuff in my config is just me dogfooding to see what works and what doesn't.

And of course home manager and nixos also have modules for that you can use to go on.

As far as a place for "Im creating a module for program x", I don't know yet. I can get back to you on that, but for now, what you did here is fine to be honest, or just do it and open a draft PR while you are working is fine too, just mark it as a draft so I know its not ready and I don't have to look if I don't want. So, for now, a discussion of some kind, or a draft PR. If it gets too much I can make a megathread and pin it

Oh, also. Shells should ideally use the config.wrapperImplementation = "binary"; setting by default so you can use them on mac in shebangs, so don't use config.runShell if you can avoid it, try to just set the zdotdir variable and do it from there, it should be possible.

Also you should do all building you can in config.drv.buildPhase or config.drv.installPhase and pass strings there, that way ${placeholder "out"} works and can be used to refer to the final wrapper in all the options you make, don't build it in a separate drv like I do in that file if possible.

[FluxZA]

I really like the mission statement! I think this approach is great and I agree with the feeling that it could be a big feature for nix moving forward.

With that in mind I do have some suggestions, mainly around how the project is presented and the docs. If you are interested, I would be happy to share them, but I don't want to impose, and they are just my opinions. I don't think they are necessarily the best approach, just what I think a good approach would be.

---

As for the feature's you mention. I don't think I fully understand them yet, hence my hesitance to use them in the zsh wrapper. I have yet to move my neovim from Cats to wrappers, so I haven't had hands on experience with specs. It is cool that you have found some uses for them, and I definitely am keen to try understand them better and use them for the zsh wrapper in later iterations if they make sense.

[BirdeeHub]

I am not sure it would make sense to use wlib.types.spec in the zsh wrapper to be honest.

I suppose zsh has plugins, which may have config and/or dependencies (having people just source the plugins is fine) so maybe that could be a dalOf or dagOf type with an extra value for some associated configuration at some point

But also, most zsh plugins don't have dependencies, and don't have much config, and you just source them. That may be overcomplicating it.

Honestly I would just expect a dir option, the files as string content from nix individually, (like you have but with them not mutually exclusive), maybe an option for alias, maybe an option for sourcing nix profile paths and/or the system config paths, and then environment variables are already covered by the env option so no need to do those.

Maybe you could have an option for the output from compinstall? But all you have to do with that is source it, even that isn't really all that necessary unless you wanted to do an option for all the options compinstall lets you set. So honestly I would lean towards not doing that and letting people do the setup and then source the output themselves

But outside of the plugins list, I'm not sure you really want anything to have any more ordering than a normal lib.mkBefore or lib.mkAfter would already be able to provide. The rest you probably just want to let people write a zsh config? It is up to you. It is your module, I'm trying to make it as easy as possible to make modules like it, so if you need anything let me know XD

They were necessary for finer control over the core sets of options that everything ends up setting. I'm not sure people will need to do more than make use of those for the majority of programs.

However, some of the others like stringable, attrsRecursive, file, or subWrapperModule I do expect to see quite frequently as time goes on (ok, maybe not file, file is ok... Im still somewhat undecided on file. Its probably a good choice for your options for the zsh files tho, so thats nice. File is better than just types.lines unless there is already a good way to provide a path)

[BirdeeHub]

And yeah Im doing docs right now if you have input let me know!

I don't know for a fact what the best way to do them is, I do want input!

All I know is that when I tried to use the regular methods of generating module docs, it was just a big wall of options and it was not clear what was from where. It looked much better when I made it clear and grouped it by what was from which module with a description or maintainer.

So my plans were just to do that better, and make some kind of API for other people to generate that for their projects, for if they want to include a wrapper module with their flake for their program rather than or in addition to submitting it here or whatever.

So, any sort of PR, advice, or concerns about docs (or anything else) is welcome, but the docgen itself is somewhat complex and it will likely be faster to tell me if it is something that needs to be handled at that level rather than just editing some markdown (at least for now while I am still writing it)

---

If it is anything about the intro, the getting started page, or the random in between pages for the lib, helper, and wrapper modules, that's all just markdown, I don't have any attachments to it other than that it needs to become more informative rather than less informative over time. And that we should avoid breaking links by using redirects where possible. So, that is easily changeable by anyone with an opinion.

If it is about how things get generated, I am open to input, but that is actual code so takes more effort to make changes to. At least for now, for example, I will be sticking with mdbook, and I will be trying to group the options with the closest parent module with a description or maintainer. Pretty much anything else, I can change reasonably well.

---

Mostly unrelated to the docs conversation:

I also really do not want to add more inputs to the main flake and intend to refuse all suggestions which require it if possible. That is why the docs website and the tests are built via a ci flake instead of the main one, in case inputs are required for that.

For example, 1 reason I did not want to include the building of home manager modules or nixos modules in the flake-parts module, is that I would need to import their modules module which would require an input, and/or overspecify how people manage their home manager or nixos modules.

Instead, I handled the things that were up to me there, and gave a function for generating the modules of other types.

Maybe in the future when we can also install services, it will be worth making a function for each other type rather than just a single one that can be used generically as we have now, as then each module would then have to set more than 1 value in config.

[FluxZA]

Thanks for the input on the zsh module, I will keep it in mind when I am deciding what to include.

As for the docs, I think most of my ideas would fall under the general section i.e. things which I can just add to the markdown and submit a PR for you to see what you think, so I will do that. My biggest suggestion is a concepts section, kind of like an index which gives a more in depth explanation on some things which are covered elsewhere. Eg. You don't want to have a huge description in the types file for the DAL/DAG, but for me at least they were difficult to understand, so having a section with a more verbose explanation and maybe some examples would be helpful. (Or for me at least it would have been)

One idea I had for the docgen is that if it is possible, minimising the options in the sidebar, especially the carry overs from the default lib modules, would make navigation easier. I missed that there was a tips and tricks section for the neovim wrapper the first 2 times I looked through it.

[BirdeeHub]

One idea I had for the docgen is that if it is possible, minimising the options in the sidebar, especially the carry overs from the default lib modules, would make navigation easier. I missed that there was a tips and tricks section for the neovim wrapper the first 2 times I looked through it.

So, right now those are being auto detected by mdbook because they have a heading with # or ##

In the summary I am only explicitly setting in the SUMMARY.md file the files themselves, although I could technically do more fine-grained generation of the SUMMARY.md file if necessary (without needing to change the mdbook module. It's pretty good)

Maybe there is a setting I can set, and change it at the mdbook level, and if not, we can see how like, ### looks in the raw markdown and stuff and if its alright it should skip those for the sidebar when generated?

It would be nice if I could get it such that if a module was not expanded the links for its options do not appear in the sidebar, and then when you expand them they do, but I have not figured out how to do that yet. I am not sure if that is built in to some sort of attribute I can set via the limited html syntax it supports? Can I tag stuff with html ids arbitrarily? Maybe some kind of mdbook plugin would be able to do it? But then the "tips and tricks" would be followed by just modules/makeWrapper in the sidebar until you expanded the makeWrapper options which might be a nice way to handle that.

The main wlib attrset ones though (wlib, wlib.types, wlib.dag) are generated by pkgs.nixdoc, so hopefully I can set that at the mdbook level otherwise Im going to have to use some sed haha (luckily it is only 3 files, 4 when I add a docs api)

But regardless, the input on this is helpful, and I will address it soon when I have time to do the effort for the next iteration on the docgen stuff.

As for the docs, I think most of my ideas would fall under the general section

Absolutely, honestly, I'm not a talented writer of things which are not code, and I have the curse of "I already understand it".

I have been slowly making them better as time goes on, but I also have a lot of other things that actually affect the function of the thing to do.

I wrote a draft of an intro, and copied some of the intro from lassulus wrappers, I had AI rewrite it, I rewrote it again, I had AI rewrite it again, repeat about 2 more times, and then came back and added a few more sections for mkInstallModule and flake-parts when I added those, and this was what they ended up looking like

All that stuff is right here and it won't be moving anywhere when I do the docgen stuff, it is fine there.

If you want to add an extra page, that is also pretty easy, it is using the mdbook module:

nix-wrapper-modules/ci/docs/default.nix

Lines 118 to 123 in b0156b2

	{
	name = "Getting Started";
	data = "numbered";
	path = "md/getting-started.md";
	src = ./md/getting-started.md;
	}

^ you would just add a new entry like this one and add the new markdown file to the directory

Do whatever you think is the best, I will be happy to help make sure the info is correct and give input if I have any.

I was planning to move the thing about the lassulus/wrappers repo this one was inspired by to another "philosophy" page or something, I'm not sure it is time for that yet but if that looks better, feel free, but if you do that, include a redirect. Likewise, if you change the headings of the sections in a way that changes the link (meaning, moving the heading to another page or changing the wording of the heading itself) you should also include one. Im not worried about redirects for when people change option names, it will at least still take them to the right page, but for the non-generated docs we should do that.