Docs: build.jobs reference documentation

[humitos]

Small reference documentation for build.jobs and all the pre/post jobs allowed.

Related #9016

[ericholscher]

Suggested change

	Commands to be run before or after a Read the Docs pre-defined job.
	This allows you to run custom commands at a particular moment in the build process.
	Commands to be run before or after a Read the Docs pre-defined build step.
	This allows you to run custom commands at various times in the build process.
	A few common use cases for this area:
	* Modifying the state of the checkout of your repository
	* Stopping a build by returning a non-zero exit code on certain conditions
	* Running a command to process generate markup files prior to building

Thinking more about this, we probably need to define this feature a lot more explicitly in the docs somewhere, particularly around exit codes.

[humitos]

I didn't mention use cases here because none of the other config keys do that. Instead, I suggested writing a guide explaining what are the known use cases we have already and expanding on each of them clearly.

I see this page as reference documentation that only explains what are the possible/valid config keys and values of each of them, but it does not talk about use cases. I'd include the link to that guide page here once we write it, tho, as we do with build.tools.python and the Conda Support link (https://docs.readthedocs.io/en/stable/config-file/v2.html#build-tools-python)

What do you think?

[ericholscher]

Should we make this a string for consistency?

Suggested change

	os: ubuntu-22.04
	os: "ubuntu-22.04"

[humitos]

This one, in particular, is not required to be a string. However, we can declare it as it. We should change the other one as well where I copied it from https://docs.readthedocs.io/en/stable/config-file/v2.html#build

[ericholscher]

I don't really know what this means. Can we communicate it more explicitly somehow? What else would users try to do here, that might be wrong?

[humitos]

I'm trying to avoid users writing something like

build:
  jobs:
    post_install: pip install mypackage

when it should be

build:
  jobs:
    post_install: 
      - pip install mypackage

[ericholscher]

Seems like the above note is probably better noted here?

[humitos]

I'm merging this so it goes out tomorrow together with the deploy and the build.jobs feature. We can come back to this comment later #9056 (comment) and also continue the discussion about how the documentation should be written in #9067