SIG: Documentation meeting on 2024-06-01
Attendees:
Agenda
- Lib documentation
- @minion: pkgs.writeScript & associated writers
- @minion: I’m in the process of getting noogle working, etc. so that I can test some of this locally
- @dfh: Noogle is the search for lib, right?
- @minion: yes, https://noogle.dev/
- @minion: pkgs.writeScript & associated writers
@isabel, @liketechnik: What else should we document from lib- Not present, carry forward to next week
- Wiki pages
- @minion (on behalf of @coded): community templates
- @minion: Coded has made Onboarding | Auxolotl Wiki
- @minion: he plans to continue filling in more community templates over the next weeks … it’s helpful to have examples so we can make more of these which fit what we want easily when SIGs/Committees make pages of these types
- @dfh: Would it make sense to start with a “How to document your SIG/Committee” guide under the templates?
- @dfh: like an instruction manual for the templates
- @minion: Yea, that sounds quite good, I’d be happy to see this at https://wiki.auxolotl.org/en/wiki-templates/community or https://wiki.auxolotl.org/en/wiki-templates!
- @minion: Formatting tools (treefmt challenges)
- @minion: we can’t enable all the formatters at once because you have to download them all…
- @minion: …we were planning to make a module
- @dfh: would it make sense to start treefmt with markdown + nix and then do additional things later on? do we need to cover everything from the getgo?
- @dfh: can we have a flake template with the formatters?
- @minion: yea, that sounds great! GitHub - auxolotl/templates: Nix templates for quickly bootstrapping a system with Auxpkgs might be the place for this!
- @minion: e.g. we’ve got a “c” template, we should have treefmt there
- @dfh: can we have a flake template with the formatters?
- @minion: yea, that would be maybe a simpler way to start off than making a module/etc.
- @dfh: can we set sensible defaults enabled by default?
- @liketechnik: other documentation index
- Looks like it’s the Resources | Auxolotl Wiki page
- @minion: looks good to me
- @dfh Me too
- @minion: might be nice to have some descriptions/etc.
- @dfh: can we add nixos-and-flakes.thiscute.world?
- @dfh: Can/ should we add a small description for each entry that explains: what is behind the link, who should read it, what solutions can I find
- @minion: Yes plz
- @minion (on behalf of @coded): community templates
- Forgejo status update
- @minion: some stuff exists, https://git.auxolotl.org
- @minion: myself and coded are working on CI before everything is migrated, we want to set up buildbot-nix (GitHub - Mic92/buildbot-nix: A nixos module to make buildbot a proper Nix-CI.). We probably will migrate some repositories over early to test everything, infra is already on there but we haven’t yet archived the old repo
- @dfh: why buildbot-nix
- @minion: it has great community support and looks like it will work great with forgejo!
- Markdown dialect/extensions
- @minion: so far, we’ve just been using “whatever wikijs does”, which is CommonMark + extensions (Markdown | Wiki.js)
- @minion: that means that we’ve used some things which aren’t quite “standard markdown”
- @minion: Examples would be like info blocks
> {.is-info}
- @minion: on https://docs.auxolotl.org we use remark, it displays some stuff slightly wrong so we want to make a plugin for it
- @dfh: I was particularly wondering if we can put a formatter into wiki.js. It feels quite weird to only enforce the formatting on direct edits to the repo
- @minion: yea, I get that, I don’t think wiki.js has the ability to do this. We could take a look and see, but we would probably be extending wikijs
- @minion: it’s unfortunate, if you have suggestions for alternative ways to do editing that we could control this for, I’d be interested, but I don’t want to force people to use git to edit our wiki
- @minion: so far, we’ve just been using “whatever wikijs does”, which is CommonMark + extensions (Markdown | Wiki.js)
- What should we do in the upcoming week?
Action items
- @dfh: I’d like to look at treefmt stuff
- @dfh: “How to document your SIG/Committee” guide
- @minion: fleshing out more of the resources page
- @minion: pkgs.writeScript & associated writers
- @coded: community templates
- @isabel, @liketechnik: What else should we document from lib
Standing reminders
- Next meeting will be at the same time next week!