update config docs

[jcgsville]

Description

A bunch of small updates to the Configuration docs. Wording tweaks for clarity, additions to fill in gaps and make things more consistent across the CLI, TS, and markdown docs.

Partially resolves #453. Should probably update the /library/run docs as well. I'll do so when I get to that page.

Performance impact

None

Security impact

None

Checklist

• My code matches the project's code style and yarn lint:fix passes.

[benjie]

Definitely good to clarify a lot of this! I'm filing this review so that I can switch to direct editorial, doing this all in GitHub comments is becoming unwieldy.

[benjie]

Massive improvement - thanks! 🙌

[benjie]

This is now live 🎉 https://worker.graphile.org/docs/config

[jcgsville]

I noticed you took out this bit

Adding the import statement tells TypeScript about the `GraphileConfig` global
namespace and the properties that
[Graphile Worker adds](https://github.com/graphile/worker/blob/c70e9db03f6ad292dcdb833714741363bd78937d/src/index.ts#L158)
to the `Preset` interface. No code from the `graphile-worker` or
`graphile-config` libraries will be included in the output JavaScript for
`graphile.config.ts` above. See the TypeScript docs for more info about
[declaration merging](https://www.typescriptlang.org/docs/handbook/declaration-merging.html)
and
[type-only imports](https://www.typescriptlang.org/docs/handbook/release-notes/typescript-3-8.html#type-only-imports-and-export).

Do you think that was a distraction / unnecessary? I thought it might help people to understand how the graphile config stuff works. Maybe better included elsewhere?

[benjie]

It was good; but when I ran the graphile config print command nothing much was output and I realised it was because we didn’t explicitly add the worker preset to the config (because it’s added for us). By adding the preset explicitly the print command worked and there was no need for the stub import type, which meant there was nothing for the note to relate to.

[benjie]

Definitely consider adding something like it to the graphile config docs though

[jcgsville]

Ah, makes sense. Sounds good 👍

[jcgsville]

added the stuff about the graphile config global namespace in my latest graphile config docs pr:

graphile/crystal#2282