Document and cleanup scripts.

[tomchristie]

Prompted by @agronholm on our chat channel.

We should add a README to our scripts directory, explaining that we're using the GitHub "scripts to pull them all" pattern, and show how that ties in with our test and publish workflows.

That'd also be a good opportunity for a bit of clean-up.

It might be neatest for our scripts directory to strictly have a 1:1 mapping with the steps we have in our workflows.

Here's how our two workflows currently look...

      - name: "Install dependencies"
        run: "scripts/install"
      - name: "Run linting checks"
        run: "scripts/check"
      - name: "Build package & docs"
        run: "scripts/build"
      - name: "Run tests"
        run: "scripts/test"
      - name: "Enforce coverage"
        run: "scripts/coverage"

      - name: "Install dependencies"
        run: "scripts/install"
      - name: "Build package & docs"
        run: "scripts/build"
      - name: "Publish to PyPI & deploy docs"
        run: "scripts/publish"

And our scripts...

$ ls -1 ./scripts/
build
check
clean  # This doesn't exist in a workflow.
coverage  # Called into by `test` when running locally.
install
lint  # This doesn't exist in a workflow.
publish
test
unasync  # Called into by `check` and `lint`

Perhaps a neater approach would be...

• scripts/install - When running locally this should always start by removing any existing venv, coverage and build directories. We don't need scripts/clean then.
• scripts/check and scripts/lint - I'd suggest we just have scripts/lint. Run scripts/lint --fix to update files in-place.
• scripts/unasync - Should be a separate step in the workflow. Run scripts/unasync --fix to update files in-place.

So that each script is always a single workflow step.