Minutes from SIG: Documentation on 2024-07-20

minion · July 20, 2024, 5:46pm

SIG: Documentation meeting on 2024-07-20

Attendees:

Skyler Grey (@minion)
Axel (@Axel)
Pyrox (@pyrox)

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

@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!