From dea013f04587d31c7cdfb8be0e6299796c77649d Mon Sep 17 00:00:00 2001 From: Tony Worm Date: Sun, 19 May 2024 15:18:34 -0400 Subject: [PATCH] more docs work --- .../content/getting-started/hof-attributes.md | 29 +++++-- docs/content/getting-started/task-engine.md | 20 ++--- docs/content/task-engine/_index.md | 77 +------------------ 3 files changed, 38 insertions(+), 88 deletions(-) diff --git a/docs/content/getting-started/hof-attributes.md b/docs/content/getting-started/hof-attributes.md index ba91d8dd..af6ad39f 100644 --- a/docs/content/getting-started/hof-attributes.md +++ b/docs/content/getting-started/hof-attributes.md @@ -5,12 +5,31 @@ weight: 70 --- {{}} -Hof denotes major features with a `#hof` definition -and has several attributes you can use as shorthand. +The `#hof` definition is how generators, datamodels, and workflows are discovered. +Several attributes allow you to write shorthand for common settings. {{}} -- @gen -- @flow -- @datamodel + +### The Attributes + +By now, you have seen hof's attributes in the previous getting-started sections. +Hof turns these CUE attributes into `#hof` configuration. + +- `@gen()` - the root of a generator +- `@datamodel()` - the root of a datamodel +- `@flow()` - the root of a workflow or a task type + +Datamodels and workflows have a few more attributes +that can be specified under their root. +They are covered in the respective sections on each. + +### Schema + +The following is the schema for `#hof`. +Many generators, workflows, and datamodels +you import and use will fill this in for you. + +You can embed the following schema in order to reference the content. +Hof will automatically inject it during the loading process to ensure correctness. {{< codePane title="hof/schema.Hof" file="code/hof-schemas/hof.html" >}} diff --git a/docs/content/getting-started/task-engine.md b/docs/content/getting-started/task-engine.md index 2054197c..10955021 100644 --- a/docs/content/getting-started/task-engine.md +++ b/docs/content/getting-started/task-engine.md @@ -55,18 +55,18 @@ Global Flags: ### Tasks & Schemas You can find the schema and example for all tasks in -[the hof/flow reference section](/reference/hof-flow/tasks/) +[the hof/flow reference section](/task-engine/tasks/) -- `api` +- [api](/task-engine/tasks/api/) - Call - Serve -- `csp` (communicating sequential processes) +- [`csp`](/task-engine/tasks/csp/) (communicating sequential processes) - Chan - Send - Recv -- `cue` +- [`cue`](/task-engine/tasks/cue/) - Format (print incomplete to concrete CUE values) -- `gen` (generate random values) +- [`gen`](/task-engine/tasks/gen/) (generate random values) - Seed - Now - Str @@ -76,11 +76,11 @@ You can find the schema and example for all tasks in - UUID - CUID - Slug -- `hof` +- [`hof`](/task-engine/tasks/hof/) - Template (render a hof text/template) -- `kv` +- [`kv`](/task-engine/tasks/kv/) - Mem (in-memory cache) -- `os` +- [`os`](/task-engine/tasks/os/) - Exec - FileLock - FileUnlock @@ -94,9 +94,9 @@ You can find the schema and example for all tasks in - Stdout - Watch - WriteFile -- `prompt` +- [`prompt`](/task-engine/tasks/prompt/) - Prompt (interactive user prompts, like creators) -- `st` (structural) +- [`st`](/task-engine/tasks/st/) (structural) - Mask - Pick - Insert diff --git a/docs/content/task-engine/_index.md b/docs/content/task-engine/_index.md index 7ba55d01..f730e98d 100644 --- a/docs/content/task-engine/_index.md +++ b/docs/content/task-engine/_index.md @@ -37,73 +37,7 @@ It has more task types and capabilities.
hof flow -h -{{}} -run file(s) through the hof/flow DAG engine - -Use hof/flow to transform data, call APIs, work with DBs, -read and write files, call any program, handle events, -and much more. - -'hof flow' is very similar to 'cue cmd' and built on the same flow engine. -Tasks and dependencies are inferred. -Hof flow has a slightly different interface and more task types. - -Docs: https://docs.hofstadter.io/data-flow - -Example: - - @flow() - - call: { - @task(api.Call) - req: { ... } - resp: { - statusCode: 200 - body: string - } - } - - print: { - @task(os.Stdout) - test: call.resp - } - -Arguments: - cue entrypoints are the same as the cue cli - @path/name is shorthand for -f / --flow should match the @flow(path/name) - +key=value is shorthand for -t / --tags and are the same as CUE injection tags - - arguments can be in any order and mixed - -@flow() indicates a flow entrypoint - you can have many in a file or nested values - you can run one or many with the -f flag - -@task() represents a unit of work in the flow dag - intertask dependencies are autodetected and run appropriately - hof/flow provides many built in task types - you can reuse, combine, and share as CUE modules, packages, and values - -Usage: - hof flow [cue files...] [@flow/name...] [+key=value] [flags] - -Aliases: - flow, f - -Flags: - -d, --docs print pipeline docs - -f, --flow strings flow labels to match and run - -h, --help help for flow - -l, --list list available pipelines - --progress print task progress as it happens - -s, --stats Print final task statistics - -t, --tags strings data tags to inject before run - -Global Flags: - -p, --package string the Cue package context to use during execution - -q, --quiet turn off output and assume defaults at prompts - -v, --verbose int set the verbosity of output -{{< /codeInner >}} +{{}}
@@ -112,15 +46,12 @@ Global Flags: `hof/flow` accepts CUE entrypoints like the other commands. There is CLI sugar for -- flows: `@path/name` is sugar for `-f path/name` +- flows: `@path/name` is sugar for `-F path/name` - tags: `+key=value` is sugar for `-t key=value` -Flags: +Useful Flags: -- `-f`/`@` is used to select a flow by name in `@flow()` +- `-F`/`@` is used to select a flow by name in `@flow()` - `-t`/`+` is used to inject strings into tags `@tag()` -- `-l`/`--list` prints the list of discovered flows -- `-d`/`--docs` prints additional flow details and docs - `--progress` will print task progress for the events found, pre, & post -- `--stats` will print task times and dependencies at completion