2024-01-04 Documentation team meeting notes #102

Infinisil · January 4, 2024, 4:22pm

Notes

Long-term implementation in Nix itself
nixos-render-docs
- Big automated refactor: treewide: 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: https://github.com/nix-community/nixdoc/pull/91
- 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. · GitHub
Related: https://github.com/NixOS/nixpkgs/pull/108063

@danielsidhion: Function arguments in docs are inconsistent, e.g.
- Nixpkgs Reference Manual
  - This style looks pretty good, sounds good to make it be used consistently
- Nixpkgs Reference Manual
@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