In reply to @olafklingt:matrix.org
how is the ":::" annotation called in sphinx? i wonder what the implications of more or less periods is.

In reply to @terru:raccoon.college
oh btw, while we're talking about admonitions: the doc/README.md still contains links to docbook for the types of admonitions which are supported. Is this in any way useful or intentional, or just a migration leftover and therefore a bug? (I found it a little confusing when i noticed it)

In reply to @terru:raccoon.college
sure: https://github.com/NixOS/nixpkgs/pull/305328

In reply to @terru:raccoon.college
(and while we are on the topic of leftover docbook mentions: anyone got opinions on this issue of mine?)

In reply to @fricklerhandwerk:matrix.org
Yeah just ditch those references. Thanks a lot!

In reply to @olafklingt:matrix.org
I started to think/brainstorm about the NixOS manual again. And i remember that fricklerhandwerk recently said that he thinks "a lot of things in the manual should be on the wiki". What was did you had in mind with of that statement?

In reply to @olafklingt:matrix.org
this closed pr https://github.com/NixOS/nix.dev/pull/964 triggered my brainstorming mind to think about the possibility to have testable tutorials.
What if every tutorial is an annotated nixos-test?
For me the question is not focused on the style of annotation right now.
But rather if you have ideas why an attempt to realize this would be futile?
maybe to difficult to realize for potential content contributors (deteriorating)?
maybe to complex to implement correctly (endless poc...)?

I find this to be a bit of a rabbit hole, because in my opinion (which may as well be very wrong), all of the tooling we have for that is near-useless for our purposes. Which doesn't make it impossible to do anything about the problem of tutorials diverging from the code, but raises the question of how to approach it regardless.

There are three ways I currently see, and find all of them to be a stretch:

• Add NixOS tests that accompany tutorials. Problem: duplication and a mess of a setup
• Use https://github.com/OceanSprint/tesh to extract test cases from tutorials. This would cover many use cases, but the tool is not actively developed, and there are lots of open questions. I think it is worth trying out.
• Do something completely different, as sketched here: https://github.com/fricklerhandwerk/beast. Problem: This very unorthodox and requires building some infrastructure first, so there's high risk of diverting attention from what we may think is more important.

In reply to @olafklingt:matrix.org
this closed pr https://github.com/NixOS/nix.dev/pull/964 triggered my brainstorming mind to think about the possibility to have testable tutorials.
What if every tutorial is an annotated nixos-test?
For me the question is not focused on the style of annotation right now.
But rather if you have ideas why an attempt to realize this would be futile?
maybe to difficult to realize for potential content contributors (deteriorating)?
maybe to complex to implement correctly (endless poc...)?

I find this to be a bit of a rabbit hole, because in my opinion (which may as well be very wrong), all of the tooling we have for that is near-useless for our purposes. Which doesn't make it impossible to do anything about the problem of tutorials diverging from the code, but raises the question of how to approach it regardless.

There are three ways I currently see, and find all of them to be a stretch:

• Add NixOS tests that accompany tutorials. Problem: duplication and a mess of a setup, which needs to be maintained by hand.
• Use https://github.com/OceanSprint/tesh to extract test cases from tutorials. This would cover many use cases, but the tool is not actively developed, and there are lots of open questions. I think it is worth trying out.
• Do something completely different, as sketched here: https://github.com/fricklerhandwerk/beast. Problem: This very unorthodox and requires building some infrastructure first, so there's high risk of diverting attention from what we may think is more important.