The recipes/flutter/docs.py recipe is both extremely confusing, and under-documented.

It does, based on both properties provided, and by sniffing the branch, the following:

• [Always] PrepareDocs
  • Runs dev/bots/docs.sh
  • ... which in turn runs dev/tools/create_api_docs.dart
  • ... which, conditionally on LUCI_BRANCH=stable¹, changes the output slightly
  • ... which, conditionally on LUCI_CI=<set>, generates offline assets. I'm not sure when this is set.
• [Sometimes] Uploads the result of PrepareDocs to GS
  • ... based on validation: docs in target.properties
  • ... and if the branch is master or stable, deploys the docs to Firebase

These recipes are run from the Linux docs_* targets in //.ci.yaml:

In my mind, it would be good to:

• Consolidate .ci.yaml target properties under a docs sub-property
• Make the various optional tasks explicit instead of implied based on the current branch
• Upgrade all active branches (master, current-beta-candidate, current-stable-candidate)

A possible end result (this is very hand-wavey, and could use a longer discussion):

# .ci.yaml
targets:
  - name: Linux docs_master
    recipe: flutter/docs
    enabled_branches:
      - master
    properties:
      docs:
        generate: true|include-offline-docs
        post_process: false
        upload_to_firestore: <project-name>

/cc @jtmcdole Could be a candidate for a "my first recipes" type project for a new hire or returning SWE