Minutes from SIG: Documentation on 2024-07-20

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
            • @minion: What about trying to look at enable options?
              • @pyrox: There are still special cases… e.g. there are some forgejo action runner bits that have instance things separately
  • @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

Standing reminders

  • Next meeting will be at the same time next week!
4 Likes