gytis-ivaskevicius/flake-utils-plus

Improve exporters documentation

gytis-ivaskevicius opened this issue · 3 comments

gytis-ivaskevicius commented

I can't seem to find any documentation from devos side of things on these exporters - the only docs there are part of the code - I think usage example should be added and double-checking formatting is kinda needed (there are some weird comment indentations)

@blaggacao @Pacman99 - Does devos have some docs on this that I could steal that I have not noticed? (Of course in nice, legal, MIT manner :D )

If not - It would be great if you guys could take care of it since you guys built em

Also, there might be a bug (or maybe a missing feature) with fromOverlays exporter. Need to do some investigation. Not related to this issue

Pacman99 commented

Currently in devos docs, we just explain the fact that your overlays and packages get exported by default. In pretty much all of the outputs docs we explain how things get exported.

And it makes much more sense to include usage examples in this repo. I think the 'how it works" info is already pretty well explained in the code. The weird comment indentations from me were because of nixpkgs-fmt flattening out all comments to one indent.

I can add some more comments and explanations on how to use them in https://github.com/gytis-ivaskevicius/flake-utils-plus/blob/staging/examples/exporters/flake.nix.

I don't mind adding a doc file for them or adding a section to the README, but that might be a bit of an overkill. The exporters are pretty simple to use, each just has one or two arguments and try their best to export as many things as possible.

blaggacao commented

I agree, so in fup we do:

  • in-code docstrings
  • usage examples (these ones are missing here)

In devos, we also prefer to do proper (markdown) docs on a docs page.

In digga? — we might adopt the fup policy, since those repos are like siblings.

Pacman99 commented

In my opinion, adding usage examples in digga/devos isn't really a good idea, since you would never interact with those exporters. The packages/overlays are just exported for you. And we already describe how that happens in devos docs.

Yeah maybe digga should just start adding usage examples like and any markdown documentation can go to devos.

  • 👍2