| 23 Jun 2021 |
 ryantm | This should be useful for the sections of the NixOS manual that are more deeply nested than the Nixpkgs manual. | 03:55:56 |
 David Arnold (blaggacao) | In reply to @ryantm:matrix.org
I figured out how to convert the top-level release-notes.xml file to markdown by getting embedded docbook includes to work: https://github.com/ryantm/nixpkgs/commit/aa6b6594ef8f940169b9b426040d0259fd1bc882 Maybe the sphinx .. include:: ../README.md is already more familiar to use. There is also Paradox' @@include README.md | 11:45:25 |
| David Arnold (blaggacao) | * Maybe the sphinx' `.. include:: ../README.md` is already more familiar to use. There is also Paradox' `@@include README.md` | 11:45:34 |
| David Arnold (blaggacao) | Redacted or Malformed Event | 11:46:17 |
| David Arnold (blaggacao) | Redacted or Malformed Event | 11:54:51 |
| David Arnold (blaggacao) | 0. `.. include:` | 11:55:02 |
| David Arnold (blaggacao) | [Poll] Which?
0. .. include: myfile.md
1. @@include myfile.md | 11:55:45 |
| David Arnold (blaggacao) | 0. .. include: myfile.md | 11:55:46 |
| David Arnold (blaggacao) | I also enjoyed reading https://developer.lightbend.com/docs/paradox/current/directives/index.html | 12:28:07 |
| David Arnold (blaggacao) | Especially the @snip directive: | 12:29:46 |
| David Arnold (blaggacao) | @@snip [sysctl.nix](/nixos/sysctl.nix) { #label_filter }
| 12:31:57 |
| David Arnold (blaggacao) | Where label filter is a comment syntax to demark the code region to include into the docs. | 12:32:27 |
| David Arnold (blaggacao) | Those code regions will be tested by hydra, and when the code updates, code regions will have to be updated, too. | 12:33:03 |
| David Arnold (blaggacao) | So less documentation drift. | 12:33:10 |
| David Arnold (blaggacao) | * Where label filter is a code comment syntax to demark the code region to include into the docs. | 12:33:37 |
| ryantm | I really don't think includes are necessary in the final thing. | 13:06:21 |
| ryantm | This is just another tool to help us incrementally convert. | 13:06:58 |
| David Arnold (blaggacao) | Ah ok, got ya! 👍 | 13:48:03 |
|  tnias joined the room. | 14:40:10 |
 Jan Tojnar | ryantm: I still am not very fond of static global TOC | 15:46:36 |
| Jan Tojnar | I think building the doc tree from included documents like docbook does is better for reducing the chance of merge conflicts, among other things | 15:49:41 |
| Jan Tojnar | also having the tree would hopefully allow us to have per section TOCs | 15:50:42 |
| ryantm | Yeah, the per-section TOCs are an improvement, but I'm not sure it is worth the cost of spreading the TOC among multiple files and adding the complexity of includes. | 16:08:12 |
 Domen Kožar | I've refreshed the theme for https://nix.dev/, let me know what you think :) | 17:17:47 |
| ryantm | I like all the links to the various sections. | 17:30:34 |
 chreekat | Domen Kožar: looks incredible | 17:31:54 |
 jonringer | overflow on the contents pane, :) | 17:32:33 |
| Domen Kožar | jonringer: as in, too many levels? | 17:33:08 |
| jonringer | previously, I wasn't able to scroll the ToC | 17:33:27 |
| Domen Kožar | ah yeah, that's finally fixed | 17:33:48 |
