feat(wiki): add an introduction to creating jobs #45
Conversation
This adds a guide to the wiki that walks the reader through developing a Job with Open Job Description. The guide explains elements of the Job Template as it introduces concepts bit by bit, and shows how to use the CLI to verify and test their Jobs on their workstation. Signed-off-by: Daniel Neilson <53624638+ddneilson@users.noreply.github.com>
|
|
||
| We'll go through both options. | ||
|
|
||
| ##### 2.2.4.2.1. With a Combination Expression |
There was a problem hiding this comment.
This section needs the feature request OpenJobDescription/openjd-model-for-python#131 to be implemented before it can be published.
| ... | ||
| ``` | ||
|
|
||
| Then modify it so that it accepts script arguments: |
There was a problem hiding this comment.
script arguments or CLI arguments?
There was a problem hiding this comment.
command-line args. Clarified in doc
| The way to think about a Step in Open Job Description is that it is defining a command to run and the collection of inputs | ||
| to run the command with. This is a [map operation](https://en.wikipedia.org/wiki/Map_(higher-order_function)), if | ||
| you are familiar with that concept. You're not going to define any inputs for the command yet, so you'll be using the default | ||
| of having a single Task with empty input. The command is defined in the `onRun` Action in the skeleton above; this is | ||
| the command that is run when running a Task within a [Session](How-Jobs-Are-Run#sessions). An Action in the 2023-09 | ||
| revision of the specification [is defined as](2023-09-Template-Schemas#5-action): |
There was a problem hiding this comment.
We suddenly up the reading and tech level a lot with this paragraph and the few that follow. Consider shorter sentences and more of them.
There was a problem hiding this comment.
I've adjusted this significantly. Let me know what you think.
| they are [Format Strings](How-Jobs-Are-Constructed#format-strings) that are evaluated on the host that the command will | ||
| run on. We're going to make use of this property to create our Job. | ||
|
|
||
| You've already expressed your Job as a series of two shell scripts to run in sequence, so next you'll make use of the |
There was a problem hiding this comment.
Feels like we skipped a step- we haven't had the OpenJD example of using the script itself yet, so "you've already expressed your job as.." doesn't make much sense. We've only been running single scripts, not any Jobs yet
There was a problem hiding this comment.
Coming back with fresh eyes, I would phrase it as "We've created two scripts and can manually run them in sequence to approximate the results we want. We can use Open Job Description's concept of embedded files to put those scripts directly into a Job template, which..
| # Note: Task.File.Render refers to the file location on disk where the | ||
| # contents of the embedded file named "Render" are materialized. | ||
| command: "{{Task.File.Render}}" | ||
| args: |
There was a problem hiding this comment.
Be good to comment here that this needs to be a list as it's one area we've been people butt their heads against (including me)
| ... | ||
| ``` | ||
|
|
||
| ### 2.3. Ready for Production |
There was a problem hiding this comment.
Note to self: We should add something on the hostRequirements property in here.
| they are [Format Strings](How-Jobs-Are-Constructed#format-strings) that are evaluated on the host that the command will | ||
| run on. We're going to make use of this property to create our Job. | ||
|
|
||
| You've already expressed your Job as a series of two shell scripts to run in sequence, so next you'll make use of the |
There was a problem hiding this comment.
Coming back with fresh eyes, I would phrase it as "We've created two scripts and can manually run them in sequence to approximate the results we want. We can use Open Job Description's concept of embedded files to put those scripts directly into a Job template, which..
| # Return an error code if any command in the script fails. | ||
| set -eou pipefail | ||
|
|
||
| TMPFILE=$(mktemp) |
There was a problem hiding this comment.
This is missing the comments from the above
| ... | ||
| ``` | ||
|
|
||
| Uh-oh, there's an error! Blender couldn't find the input file. This is because all actions in a Session are always run with their |
There was a problem hiding this comment.
Nit: "The error means that Blender couldn't find the input file."
| ... | ||
| ``` | ||
|
|
||
| Also remove the definitions of the `FrameStart` and `FrameEnd` Job Parameters from the template because they are no longer used, |
There was a problem hiding this comment.
I don't think we need the rest of this example to be fully demonstrated. We can list the caveats and gotchas and move on.
| --render-frame "${FRAME}" | ||
| ``` | ||
|
|
||
| or you need to modify the template so that it has both a testing and production mode. We'll do the later in this guide to demonstrate |
There was a problem hiding this comment.
I think we should break out this guide is long enough to break out into multiple pages. If we do that, feel free to ignore some of my earlier comments are removals.
Signed-off-by: Daniel Neilson <53624638+ddneilson@users.noreply.github.com> Co-authored-by: Sean Wallitsch <5846610+shidarin@users.noreply.github.com>
Signed-off-by: Daniel Neilson <53624638+ddneilson@users.noreply.github.com>
Signed-off-by: Daniel Neilson <53624638+ddneilson@users.noreply.github.com>
ddneilson
force-pushed
the
authoring_job_template
branch
from
2570953 to
fdc1198
Compare
Signed-off-by: Daniel Neilson <53624638+ddneilson@users.noreply.github.com>
This adds a guide to the wiki that walks the reader through developing a Job with Open Job Description. The guide explains elements of the Job Template as it introduces concepts bit by bit, and shows how to use the CLI to verify and test their Jobs on their workstation.
By submitting this pull request, I confirm that you can use, modify, copy, and redistribute this contribution, under the terms of your choice.