Rewrite Rules API docs for call-by-name.

[benjyw]

No description provided.

[benjyw]

Reviewers: I recommend starting with docs/docs/writing-plugins/the-rules-api/concepts.mdx and then looking at docs/docs/writing-plugins/the-rules-api/union-rules-advanced.mdx. Those are the most substantial rewrites. The diffs are probably not instructive.

Then the remaining files are almost entirely just changing examples to use call-by-name.

[sureshjoshi]

Suggested change

	from pants.engine.process import fallible_to_exec_result_or_raise
	from pants.engine.process import execute_process_or_raise

[sureshjoshi]

Thanks for doing this metric ton of work!

I went through and made some nits, clarifications, and a few other things.

General feedback was of the form "we should immediately let the user know that we'll be revisiting a confusing topic/idea below"

If we want to bikeshed on any of this, I'm still approving - as the results here are better and more valuable than what we have online, so we could always push feedback to a follow-up PR.

[benjyw]

Thanks for the very useful comments and suggestions @sureshjoshi ! I've addressed them all.

[benjyw]

Except I kept fallible_to_exec_result_or_raise as-is in that one example, since the reader had encountered it earlier.

If we do kill that name entirely we can revisit.

[cognifloyd]

I know this is already merged. I wanted to read through anyway to see the change diffs. Very nice.

I noticed 2 minor oddities that, of course, can only be fixed in a separate PR.

[benjyw]

Fixed in #22733