Allow updating docs from unreleased pants changes, not just release

[huonw]

On a private channel on slack, @benjyw suggests that it would be very valuable to be able to make updates to released docs without a release.

There's a few options for how this might work:

1. sync all changes up to a particular commit on one of the 2.*.x branches, e.g.
   1. land a docs change to the 2.19.x branch in pantsbuild/pants
   2. trigger a doc sync here with that commit (NB. having the sync_docs workflow support using a commit is new functionality)
   3. if provided a commit, the sync docs workflow builds that version of pants to be able run the right commands
   4. the sync docs workflow continues as normal
2. sync only the changes from a particular PR or particular commit (i.e. apply a diff)
   1. land a docs change to the 2.19.x branch in pantsbuild/pants
   2. trigger a doc sync here with that PR number (NB. having the sync_docs workflow support using a PR is new functionality)
   3. if provided a PR, the sync docs workflow works out the diff in the docs (and reference?), and applies only that diff
3. something else?

The idea is that this makes it faster to go from "contributor submits a docs update" to "contributor can see their docs update live", than having to wait for the next real release.

Things we should potentially consider:

1. what happens if there's non-trivial updates to the docs that don't make sense to publish before a release? (Concrete example: Allow passing arbitrary args to PEX invocation when building FaaS artifacts pants#20237 adds a new field to some targets, which will appear in docs, and landed in 2.18.x after 2.18.0 was released. There may be others, I don't know the rate at which they occur.)
2. doc 'series' are labelled as pre-release or deprecated etc. based on the version encoded in the help-all output:

   pantsbuild.org/docusaurus.config.js

   Lines 59 to 65 in a2fff63

   	const helpAll = JSON.parse(
   	fs.readFileSync(path.join(reference_dir, "help-all.json"), "utf8")
   	);
   	const pantsVersion = helpAll["scope_to_help_info"][""]["advanced"].find(
   	(help) => help["config_key"] === "pants_version"
   	);

   So, for instance, if we do an update to 2.19.0 with some 'random' commit on the 2.19.x branch, we may need to be careful to ensure that the 2.19 docs are still labelled as current stable, not considered a pre-release
3. other things?

(Potentially in direct tension with #143.)

[thejcannon]

I think there's a universe of solutions where we have a workflow that doesn't start from scorched earth and instead just applies a diff on top of what already exists.

In this universe a workflow is given a PR (against the pants repo) and that is applied to the docs repo without any other changes (in docs or in reference)

[huonw]

Ah, yeah, that's a good idea. I've adjusted the title and edited the body to include that.

[benjyw]

Here's an example of a docs change that we'd want to be able to publish without a release: pantsbuild/pants#20544

In fact I don't even know how to view a preview of that change, so right now I'm flying blind on it.

[huonw]

I don't think we (people without credentials) could preview changes to docs in Readme before either, so even if it's not possible now, we haven't lost much. (I also have the impression that we didn't use to sync doc changes out of the release cycle very often, but maybe I missed that?)

I believe a way to preview is to make the same change to docs/ in this repo and follow https://github.com/pantsbuild/pantsbuild.org#development to get it running locally. Obviously we could ease the process, e.g. it'd be great to not have to copy things across, and even have automated previews on PRs (related to #28).