SIG: Documentation meeting on 2024-07-20
Attendees:
Agenda
- @minion: docs.auxolotl.org is redirecting
- @minion: I wondered if we should make some stopgap using a reverse proxy bodge while we get up a pages server …
- @minion: what pages server should we use for forgejo?
- @pyrox: I don’t have a horses in the race – there’s the codeberg one and the pages.gay one, I’ve not looked into it too much, both of them are probably fine
- @pyrox: codeberg pages is in nixpkgs, but there are no options for it … well, writing the service should be fine
- @pyrox: git.gay isn’t, and there’s no flake. I guess the codeberg one?
- @minion: Yeah, makes sense… I’ll look at getting that up along with buildbot
@dfh: “How to document your SIG/Committee” guide@dfh: Treefmt template/module work- @minion: Forgejo CI (Buildbot)
- @minion: needs postgres, secrets, etc.
- @Axel: Is this the forgejo inbuilt runner?
- @minion: No, it’s something different called buildbot-nix
- @minion: We considered hyrda, but they all are a bit bad
- @minion: …but buildbot-nix has really great community support!
- @minion: I am working on this … hopefully I’ll have it deployed by next week, but I know we’ve had several "next week"s
@8bitbuddhist: Template README’s on wiki- @pyrox: Nixpkgs markdown documentation generation
- @pyrox: I’m currently using MkDocs and the “material” theme
- which is fairly widely used, lots of community support, likely a good life ahead of it
- @pyrox: https://docs.auxolotl.org has the documentation homepage, it has nixpkgs, lix and Aux docs
- @pyrox: it’s searchable, massaged properly into html, etc.
- @pyrox: TODO - Aux Docs is my TODO list
- @pyrox: we’re missing the options search. The manual sucks on mobile and the options search is a little poor…
- @pyrox: Unfortunately, the thing that renders this out in nixpkgs only renders to a single page. Maybe I’ll parse this from the JSON nixpkgs provides?
- @Axel: I’m not familiar with NixOS’s options JSON - how does that work?
- @pyrox: NixOS has a function called nixosoptionsdoc - it can do either commonmarc, asciidoc, or json. I could theoretically copy that markdown … but it’s a single monolythic page, so probably I’ll have to make something custom
- @pyrox: Maybe parsing the JSON is the way forwards
- @pyrox: Might be some special cases … e.g. not everything is 2-level
- @Axel: I’m not familiar with NixOS’s options JSON - how does that work?
- @pyrox: Unfortunately, the thing that renders this out in nixpkgs only renders to a single page. Maybe I’ll parse this from the JSON nixpkgs provides?
- @pyrox: I’m currently using MkDocs and the “material” theme
@coded: Document labs lib- @minion: Neither I nor Coded will be here on Aug 3rd… do we want to reschedule, should someone else chair?
- @Axel: I’ll be starting Uni around then, not sure I can be there … I can let you know next week
- @minion: we don’t have to decide right now… but it would be a little rough of me to tell you this at the end of next week’s meeting
- @pyrox: I’m flexible - can show up if there is a meeting, or post updates in a thread, er etc.
Action Items
- @pyrox: TODO - Aux Docs
- @minion: Forgejo CI (Buildbot)
- @minion: Pages server for https://docs.auxolotl.org
- @minion: Forgejo upgrade
- @Axel: Hedgedoc update
- @Axel: Deep-diving nix-language to gain understanding, write better docs, etc.
Standing reminders
- Next meeting will be at the same time next week!