doc: update conventions with repl examples and function (in|out)puts

[DanielSidhion]

Description of changes

Closes #276829.

This PR adds two more items to the nixpkgs documentation conventions as discussed in the documentation meetings and PR reviews.

This is related to #278769, where I'm going through the nixpkgs manual to make it more consistent (and also update its content). I'm documenting the conventions I'm applying as I do this work in an effort to:

1. Let other people know the conventions I'm using, should they want to help with this work.
2. Let other people start using the same conventions for future work.
3. Have conventions clearly documented, because they weren't (or didn't even exist) before this work started.

Things done

• Built on platform(s)
  • x86_64-linux
  • aarch64-linux
  • x86_64-darwin
  • aarch64-darwin
• For non-Linux: Is sandboxing enabled in nix.conf? (See Nix manual)
  • sandbox = relaxed
  • sandbox = true
• Tested, as applicable:
  • NixOS test(s) (look inside nixos/tests)
  • and/or package tests
  • or, for functions and "core" functionality, tests in lib/tests or pkgs/test
  • made sure NixOS tests are linked to the relevant packages
• Tested compilation of all packages that depend on this change using nix-shell -p nixpkgs-review --run "nixpkgs-review rev HEAD". Note: all changes have to be committed, also see nixpkgs-review usage
• Tested basic functionality of all binary files (usually in ./result/bin/)
• 24.05 Release Notes (or backporting 23.05 and 23.11 Release notes)
  • (Package updates) Added a release notes entry if the change is major or breaking
  • (Module updates) Added a release notes entry if the change is significant
  • (Module addition) Added a release notes entry if adding a new NixOS module
• Fits CONTRIBUTING.md.

---

Add a 👍 reaction to pull requests you find important.

[bzm3r]

I do not think your changes address the issue I raised. I tried to express this once, but made mistakes. So here's the second try.

In most places, there's a "headerless" style of documentation: e.g. nixdoc generates output like so.

There might be other styles, including headered ones. It's worth understanding which "local styles" are already in use. The nixos-render-doc work might have had a list of existing styles in use (not easy to (re)find).

To fix potential issues around misunderstanding of colloquialisms, note that "to ditch" means:

To discard or abandon.

I will stick to discard from now on for clarity.

The convention as it stands now---even though a work in progress---has the potential to influence new PRs which choose to change existing f :: A -> B -> C information to relying on the Input/Output header structure alone to convey information. (There was already one discussion in the matrix around this.) This is the sense in which f :: A -> B -> C information may be discarded.

Therefore:

0. Please clarify, in the first post of this PR, what precisely was agreed upon in team meetings as to what the goal of this document is.

1. Please provide an explanation of why headers will help readers. Most function documentation styles, in most languages (e.g. Rust or Haskell) do not use headers. They rely on type information alone. to act as headers. Some third party Python documentation has subtle headers, but the official ones do not. MDN Javascript documentation does. However, the MDN documentation also has an explicit/separate page for each function (not one long scroll-through document, for example like the current Nixpkgs manual).

2. Please do not select a convention, without a summary of existing function input/output styles, and some analysis of their pros and cons. (In particular, of headerless styles.)

3. Please consider improving the structure of headerless styles, as an alternative to headers.

4. Please consider choosing to be clear about what ought to be included under each header. Otherwise, please explain why this document would prefer to leave what goes under each header up for grabs?

5. Please consider marking clearly that this document is a work in progress that does not endorse any convention yet and does not encourage its use as inspiration just yet.

[DanielSidhion]

@bzm3r
In my opinion, the changes I made do address the issue. From what I understood, this seems to be your problem with this PR:

...has the potential to influence new PRs which choose to change existing f :: A -> B -> C information to relying on the Input/Output header structure alone to convey information

And I have already addressed in the PR that the headers are there for navigational purposes, and they don't force the content to be written in any specific way. Anyone can still write f :: A -> B -> C in the documentation, but when talking about the inputs specifically, it would be best if they put it under a header. This doesn't mean f :: A -> B -> C shouldn't exist. These aren't conflicting things. f :: A -> B -> C is content, the headers exist to help navigate the manuals.

The need for headers is way less pronounced in the nixpkgs.libs section of the manual (because those are usually short), but it's definitely needed in many other places in the manual, because there are a lot of utility functions that handle a lot of stuff behind the scenes.

Please provide an explanation of why headers will help readers

1. Headers have anchor links that people can use to jump to a specific part of the document, and use in links for other people as well.
2. Manuals are used more as a consultation device. This section of the diataxis framework page helps here. Because of that, making things consistent by having headers that are standardised across the manual helps people quickly consult it.

Most function documentation styles, in most languages (e.g. Rust or Haskell) do not use headers.

The Rust documentation uses headers. I picked a random page there for std::string::String. Note how it has "Examples", "Errors", "Panics" (and so on...) headers for a lot of the functions:

• Examples for new()
• Examples for with_capacity()
• Errors for from_utf8()
• Examples for from_utf8()

Notably, the Rust documentation doesn't have an "Inputs" header because most of its functions don't have arguments with 10+ different attributes like dockerTools.buildImage, for example. Python's functions sometimes have a large number of arguments, and in my opinion it's a really bad experience to navigate their docs. Note that even then, they also have some similarities with the conventions in this PR, for example how they move examples to be the last part of each unit they're documenting: examples for regular expressions, examples for datetime.

0. Please clarify, in the first post of this PR, what precisely was agreed upon in team meetings as to what the goal of this document is.

Done.

3. Please consider improving the structure of headerless styles, as an alternative to headers.

As I wrote already, these are not conflicting things.

2. Please do not select a convention, without a summary of existing function input/output styles, and some analysis of their pros and cons. (In particular, of headerless styles.)

I believe I've already addressed that what you're calling a "headerless style" relates to the content of the documentation, not to its structure, and those are not conflicting things.

As for selecting a convention, this is exactly what we're doing in the documentation team meetings. I find an opportunity to standardise something in the nixpkgs manual, then I bring it to the meeting, we discuss it there, and we decide on something. And that is then documented in a PR just like this one.
We shouldn't be spending this much time arguing over the structure of stuff in the nixpkgs manual (and I'm only spending this much time replying to all of this because I think you're being genuine in your concerns and I respect that).

The good thing about the structure of something is that it can easily be changed later (as opposed to the content, which is way harder). If we find out later that some other structure is better, we can quickly move to it. We might need to adapt some text in the process, but we won't need to completely change the content of the documentation.

(and I already know this is inefficient and so on, all of this is already addressed in #278769 - I'm the one doing the work to bring consistency to the manuals, so I'll work this way, even though it seems inefficient, because it's what helps me make progress on the content as quickly as possible, which is ultimately what matters)

4. Please consider choosing to be clear about what ought to be included under each header. Otherwise, please explain why this document would prefer to leave what goes under each header up for grabs?

It should be up to whoever's writing the documentation to figure out what content goes where, and even whether they should stick to the convention or not. I can't predict all the possible content that goes in the manuals, but I do know that a good part of it documents utility functions, and those follow roughly the same documentation structure. Hence why a convention for following the same structure (if it makes sense, which is also to be determined by whoever's writing the documentation).

I thought this was kind of implied in the conventions, but I'll update the PR to make it clear that the conventions are about keeping a consistent structure in the manuals.

5. Please consider marking clearly that this document is a work in progress that does not endorse any convention yet and does not encourage its use as inspiration just yet.

This document does encourage people to use the conventions laid out in it. That's (also) why they're being documented.

[nixos-discourse]

This pull request has been mentioned on NixOS Discourse. There might be relevant details there:

https://discourse.nixos.org/t/2024-01-15-documentation-team-meeting-notes-104/38305/1

[bzm3r]

@DanielSidhion Okay: I will step out of your way then, and not raise further issues here on this point. If in the future I feel that that the Input/Output header style does not work well, I'll create a separate PR to address that.

We shouldn't be spending this much time arguing over the structure of stuff in the nixpkgs manual (and I'm only spending this much time replying to all of this because I think you're being genuine in your concerns and I respect that).

Could you update the first post of this PR again with what was discussed in this documentation team meeting?

[infinisil]

I feel like this is so obvious that we don't need to mention it

Though hopefully in the future the input attribute docs would be automatically generated by nixdoc ;)

[infinisil]

Reviewed in the docs team meeting, looking good!

[nixos-discourse]

This pull request has been mentioned on NixOS Discourse. There might be relevant details there:

https://discourse.nixos.org/t/2024-01-25-documentation-team-meeting-notes-106/38792/1