2024-01-25 Documentation team meeting notes #106

[Infinisil]

• Video conference
• GitHub project board
• Team details
• Past meeting notes
• Attendees: @infinisil, @danielsidhion, @henrik-ch
• Notes by: @infinisil

Notes

• @danielsidhion: Ready to merge:
  • Merged doc: add types to template by fricklerhandwerk · Pull Request #281220 · NixOS/nixpkgs · GitHub
  • Merged Fix typo in dotnet.section.md by Samasaur1 · Pull Request #282685 · NixOS/nixpkgs · GitHub
  • Merged Note on how to use shadowSetup with buildLayeredImage by unhammer · Pull Request #267220 · NixOS/nixpkgs · GitHub
• All of the above PRs didn’t adhere to commit guidelines
  • Recent discussion on this: CI for commit title guidelines adherence · Issue #281573 · NixOS/nixpkgs · GitHub
• @danielsidhion: PRs for review:
  • Merged doc: update conventions with repl examples and function (in|out)puts by DanielSidhion · Pull Request #280520 · NixOS/nixpkgs · GitHub
  • Merged doc: add missing attribute to example in dockerTools by DanielSidhion · Pull Request #283394 · NixOS/nixpkgs · GitHub
  • Updated, squashed and merged doc: Update manuals bespoke syntax by alejandrosame · Pull Request #264450 · NixOS/nixpkgs · GitHub
  • Merged doc: update dockerTools.pullImage content and use doc conventions by DanielSidhion · Pull Request #283106 · NixOS/nixpkgs · GitHub
• @danielsidhion: From discussion on the Matrix channel, we should at least document the current tooling that produces documentation for nix/nixpkgs/nixos.
  • Idea is that this will help figure out tooling to split nixpkgs manual, and ideally unify documentation building for all projects.
  • Let’s start with a list of all tools that go into building the docs for the projects, and then we can add more information about each tool.
  • Nixpkgs
    • GitHub - nix-community/nixdoc: Tool to generate documentation for Nix library functions [maintainer=@infinisil] · GitHub
    • Nix code to determine function locations: nixpkgs/doc/doc-support/lib-function-locations.nix at 875cce1e7225f3bb4a7947eb2df59d11fb300f9e · NixOS/nixpkgs · GitHub
    • For config, options are written in the module system, also rendered with nixosOptionsDoc
    • nixos-render-docs
  • NixOS
    • nixos-render-docs
    • nixpkgs/nixos/doc/manual/default.nix at 875cce1e7225f3bb4a7947eb2df59d11fb300f9e · NixOS/nixpkgs · GitHub
    • Nix code to create a JSON from option docs
      • See baseOptionsJSON and nixosOptionsDoc
  • Nix
    • mdBook
    • See Systematize `builtins.fetchTree` docs by Ericson2314 · Pull Request #9732 · NixOS/nix · GitHub
  • nix.dev
    • sphinx
  • What else? What about the tooling involved in publishing the docs after they’re built?
    • nix.dev: GitHub Actions for every commit + Netlify: nix.dev/.github/workflows/build-and-deploy.yml at 46a79276910fc96aae3d19aaaab72e519ddd5dfb · NixOS/nix.dev · GitHub
    • nixos.org: GitHub Actions updating flake lock every day: https://github.com/NixOS/nixos-homepage/blob/e3a57cead98b1e3a6d4acf26ff6a9ab1ba6ed865/.github/workflows/cron.yml
      • Nix: Includes master branch and latest-release branch (force pushed to??)
      • Nixpkgs: Uses nixos-23.11 and nixos-unstable branches, so depends on Hydra channel updates
    • Not used, but Hydra also builds all (?) manuals, e.g. Making sure you're not a bot!
  • Things being built:
    • Doctester for manuals @mightyiam
    • RFC 145 implementation by @hsjobeki & Noogle
      • Currently nixos-render-docs: cannot render commonmark · Issue #280514 · NixOS/nixpkgs · GitHub
    • Split Nixpkgs and NixOS manual into multiple pages by @ryantm
      • https://github.com/NixOS/nixpkgs/pull/108063
      • nixos-manual with mmdoc by ryantm · Pull Request #254434 · NixOS/nixpkgs · GitHub
    • Previous effort by @FridH:
      • nixpkgs manual in CommonMark using sphinx+myst and jupyter-book by FRidh · Pull Request #105036 · NixOS/nixpkgs · GitHub
• @danielsidhion Decent filter for finding doc Nixpkgs PRs:
  Pull requests · NixOS/nixpkgs · GitHub
  Would be good to expose that somehow
  • @infinisil: GitHub projects can have a workflow that automatically adds matching items to the project