Add help HTML for user-facing Describables #219
Conversation
This will help enable INFRA-1053 (auto-generation of help for Declarative directives, like the step documentation on jenkins.io).
|
This pull request originates from a CloudBees employee. At CloudBees, we require that all pull requests be reviewed by other CloudBees employees before we seek to have the change accepted. If you want to learn more about our process please see this explanation. |
|
@rtyler @bitwiseman I included you two because these are help docs that will eventually end up in the auto-generated docs on jenkins.io, so I wanted to make sure you read my probably crappy versions. =) |
| --> | ||
|
|
||
| <p> | ||
| If true, <code>docker pull ...</code> will always be run, even if the image tag is already present. |
There was a problem hiding this comment.
would probably be helpful to say why this is useful. E.g. the latest tag has moved.
| --> | ||
|
|
||
| <p> | ||
| The job or stage will be run in a Docker container using an image built from the <code>Dockerfile</code>. |
| --> | ||
|
|
||
| <p> | ||
| If specified, this will be used as the custom workspace on the agent, underneath the workspace root on that agent. |
There was a problem hiding this comment.
This might need clarification. What does "underneath the workspace root " really mean for example.
There was a problem hiding this comment.
I honestly can't think of a better way to put it. Will think on it.
There was a problem hiding this comment.
Maybe just an example would be enough?
| --> | ||
|
|
||
| <p> | ||
| The label to use. |
There was a problem hiding this comment.
It is probably people that are new to Jenkins that will read these help files. So what is a label? Perhaps link to some chapter in the user docks somewhere?
|
|
||
| <p> | ||
| The job will not run on any agent, requiring specifying agents on each stage. Note that this has no effect when | ||
| specified on a stage. |
There was a problem hiding this comment.
Does that mean if you specify agent none on a stage it will use one anyway?
Reading things out of context is fun :)
| --> | ||
|
|
||
| <p> | ||
| Execute the stage if the build's SCM changelog contains a given <code>java.util.regex.Pattern</code>, specified as |
There was a problem hiding this comment.
Link to https://docs.oracle.com/javase/8/docs/api/java/util/regex/Pattern.html would make peoples life easier I think.
|
Merging this in so it can be in the 1.2.5 release - @rtyler and @bitwiseman, always happy to make changes/take PRs later. |
postconditions aren't included, because I regrettably didn't make themDescribables. So they'll need to be handled specially in the doc generation. Ah well.