2024-01-04 Documentation team meeting notes #102

Infinisil · January 4, 2024, 4:22pm

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

Notes

https://github.com/NixOS/rfcs/pull/145

Long-term implementation in Nix itself
nixos-render-docs
- Big automated refactor: migrate doc comments by hsjobeki · Pull Request #262987 · NixOS/nixpkgs · GitHub
- ToC breaks because everything needs an id
- How the Nixpkgs manual gets rendered:
  - nix (lib) ->(nixdoc) markdown ->(nrd) html
  - markdown (doc) ->(nrd) html
- Short-term nixdoc: init support for doc-comments by hsjobeki · Pull Request #91 · nix-community/nixdoc · GitHub
- Should ids be autogenerated in nixos-render-doc?
  - @infinisil: We want the manually written markdown documents to have persistent ids for external links to keep working, so they should not be optional
- It’s not that necessary to have persistent ids for headings within generated documenation, since it’s all fairly close together.
  - nixos-render-doc should not require ids for these generated ones
- Task: Implement some way to tell nixos-render-doc that under the generated documentation, no ids are necessary. Idea:
```
# Function docs {#function-docs}

## lib.asserts {#asserts}

### lib.asserts.assertAll {#asserts-assertAll}


#### Example

### lib.asserts.assertAny {#asserts-assertAny-no-nested-ids}

#### Example
```
- Suggestion: Investigate for like 1h, write an issue and ping @pennae
For the future consider something like GitHub - stepchowfun/tagref: Tagref helps you manage cross-references in your code.
Related: doc: add nixpkgs manual split into multiple pages by ryantm · Pull Request #108063 · NixOS/nixpkgs · GitHub

Convention for documenting attributes and arguments to functions

@danielsidhion: Function arguments in docs are inconsistent, e.g.
- Nixpkgs 24.05 manual | Nix & NixOS
  - This style looks pretty good, sounds good to make it be used consistently
- Nixpkgs 24.05 manual | Nix & NixOS
@infinisil: Sounds good, it’s hard to make sure it’s becoming consistent
- Ideally also document the style somewhere so other people can easily adhere to it
@mcdonc: Willing to help out