jenkins.io
jenkins.io copied to clipboard
jenkins-infra
[INFRA-1053] Generate automated documentation for options/parameters in Declarative Pipeline
We already have tooling for Pipeline steps which generates a zipball that the jenkins.io build process already downloads.
I think what would be ideal is to have the options and parameters for Declarative generate single asciidoc documents with:
- Symbol name
- Description from help text
- Provided by: Pipeline or
- Parameters
- ???
Originally reported by rtyler, imported from: Generate automated documentation for options/parameters in Declarative Pipeline
- status: In Progress
- priority: Critical
- resolution: Unresolved
- imported: 2022/01/10
This'll be pretty trivial to do - I'd say it'd be useful in the same directives/sections we're providing possible values for in the editor. That is - not just options and parameters, but triggers, agent, when, post... All of those are either extension points or have a well-defined filter for determining what contents are allowed, so might as well go whole hog.
I'd consider the priority on this to be higher than Minor. It's frustrating trying to use pipeline but continually having to figure out what undocumented features are.
For anyone else ending up here from the documentation, for parameters I've found the best resource to be this chunk of source:
Yes - doc'ing the available parameters and how to's on the Pipeline syntax page would have saved much googling, trial and error, wailing, and gnashing of teeth...
In case it helps anyone looking to use the credentials parameter in declarative (mentioned as possible using the .groovy link above), I found a couple ways to skin the cat, but this method is the most "declarative" vs. "scripted" and seems to be working.
Undoubtedly, there's something wrong with the below (for ex. I have no idea what the credentialType values should be, or if required is required 
), OR it will break with the next update to any of the pipeline plugins (been burned many times these last few months), but for now, this seems to be doing the trick to help collect a Jenkins user as a parameter for a maven/artifactory/maven release pipeline I'm prototyping.
At least it's some documentation that might be useful to someone.
#!groovy
pipeline {
agent { label 'any' }
parameters {
choice(name: 'PerformMavenRelease', choices: 'False\nTrue', description: 'Whether or not to perform a maven release')
credentials(name: 'CredsToUse', description: 'A user to build with', defaultValue: '', credentialType: "Username with password", required: true )
}
environment {
BUILD_USR_CREDS = credentials("${params.CredsToUse}")
}
stages {
stage ('Sync and Setup') {
steps {
echo 'BUILD_USR_CREDS_USR ' + BUILD_USR_CREDS_USR
echo 'BUILD_USR_CREDS_PSW ' + BUILD_USR_CREDS_PSW
}
}
}
}
Is the GIT Parameters plugin supported for the pipeline jenkinsfile declarative?
Andrew Bayer added a comment - 2017-01-31 23:01
This'll be pretty trivial to do
Bump
Thanks for the nice work.. things are coming together.
Ok, I spoke a bit too soon when saying it'd be trivial. =) Gonna think on this and start poking around some possible approaches for the next couple days, we'll see what I can come up with.
Ok, starting work - added help.html for all Describable extensions in Declarative directives (i.e., agent types, when conditions, and DeclarativeOption implementations for the options directive). Sadly, post conditions aren't extensions of Describable so they can't use the same tooling as the other directives. Sigh. https://github.com/jenkinsci/pipeline-model-definition-plugin/pull/219 has the work so far.
Veeeeery preliminary asciidoc generation is up at https://github.com/jenkins-infra/pipeline-steps-doc-generator/pull/12 now. We'll see if it, y'know, works.
Code changed in jenkins
User: Andrew Bayer
Path:
pipeline-model-definition/src/main/java/org/jenkinsci/plugins/pipeline/modeldefinition/options/impl/SkipDefaultCheckout.java
pipeline-model-definition/src/main/resources/org/jenkinsci/plugins/pipeline/modeldefinition/agent/AbstractDockerAgent/help-args.html
pipeline-model-definition/src/main/resources/org/jenkinsci/plugins/pipeline/modeldefinition/agent/AbstractDockerAgent/help-customWorkspace.html
pipeline-model-definition/src/main/resources/org/jenkinsci/plugins/pipeline/modeldefinition/agent/AbstractDockerAgent/help-label.html
pipeline-model-definition/src/main/resources/org/jenkinsci/plugins/pipeline/modeldefinition/agent/AbstractDockerAgent/help-registryCredentialsId.html
pipeline-model-definition/src/main/resources/org/jenkinsci/plugins/pipeline/modeldefinition/agent/AbstractDockerAgent/help-registryUrl.html
pipeline-model-definition/src/main/resources/org/jenkinsci/plugins/pipeline/modeldefinition/agent/AbstractDockerAgent/help-reuseNode.html
pipeline-model-definition/src/main/resources/org/jenkinsci/plugins/pipeline/modeldefinition/agent/impl/Any/help.html
pipeline-model-definition/src/main/resources/org/jenkinsci/plugins/pipeline/modeldefinition/agent/impl/DockerPipeline/help-alwaysPull.html
pipeline-model-definition/src/main/resources/org/jenkinsci/plugins/pipeline/modeldefinition/agent/impl/DockerPipeline/help-image.html
pipeline-model-definition/src/main/resources/org/jenkinsci/plugins/pipeline/modeldefinition/agent/impl/DockerPipeline/help.html
pipeline-model-definition/src/main/resources/org/jenkinsci/plugins/pipeline/modeldefinition/agent/impl/DockerPipelineFromDockerfile/help-additionalBuildArgs.html
pipeline-model-definition/src/main/resources/org/jenkinsci/plugins/pipeline/modeldefinition/agent/impl/DockerPipelineFromDockerfile/help-dir.html
pipeline-model-definition/src/main/resources/org/jenkinsci/plugins/pipeline/modeldefinition/agent/impl/DockerPipelineFromDockerfile/help-filename.html
pipeline-model-definition/src/main/resources/org/jenkinsci/plugins/pipeline/modeldefinition/agent/impl/DockerPipelineFromDockerfile/help.html
pipeline-model-definition/src/main/resources/org/jenkinsci/plugins/pipeline/modeldefinition/agent/impl/Label/help-customWorkspace.html
pipeline-model-definition/src/main/resources/org/jenkinsci/plugins/pipeline/modeldefinition/agent/impl/Label/help-label.html
pipeline-model-definition/src/main/resources/org/jenkinsci/plugins/pipeline/modeldefinition/agent/impl/Label/help.html
pipeline-model-definition/src/main/resources/org/jenkinsci/plugins/pipeline/modeldefinition/agent/impl/None/help.html
pipeline-model-definition/src/main/resources/org/jenkinsci/plugins/pipeline/modeldefinition/options/impl/SkipDefaultCheckout/help-skipDefaultCheckout.html
pipeline-model-definition/src/main/resources/org/jenkinsci/plugins/pipeline/modeldefinition/options/impl/SkipDefaultCheckout/help.html
pipeline-model-definition/src/main/resources/org/jenkinsci/plugins/pipeline/modeldefinition/options/impl/SkipDefaultCheckout/help.jelly
pipeline-model-definition/src/main/resources/org/jenkinsci/plugins/pipeline/modeldefinition/options/impl/SkipStagesAfterUnstable/help.html
pipeline-model-definition/src/main/resources/org/jenkinsci/plugins/pipeline/modeldefinition/when/impl/AllOfConditional/help.html
pipeline-model-definition/src/main/resources/org/jenkinsci/plugins/pipeline/modeldefinition/when/impl/AnyOfConditional/help.html
pipeline-model-definition/src/main/resources/org/jenkinsci/plugins/pipeline/modeldefinition/when/impl/BranchConditional/help.html
pipeline-model-definition/src/main/resources/org/jenkinsci/plugins/pipeline/modeldefinition/when/impl/ChangeLogConditional/help.html
pipeline-model-definition/src/main/resources/org/jenkinsci/plugins/pipeline/modeldefinition/when/impl/ChangeSetConditional/help-caseSensitive.html
pipeline-model-definition/src/main/resources/org/jenkinsci/plugins/pipeline/modeldefinition/when/impl/ChangeSetConditional/help-glob.html
pipeline-model-definition/src/main/resources/org/jenkinsci/plugins/pipeline/modeldefinition/when/impl/ChangeSetConditional/help.html
pipeline-model-definition/src/main/resources/org/jenkinsci/plugins/pipeline/modeldefinition/when/impl/EnvironmentConditional/help-ignoreCase.html
pipeline-model-definition/src/main/resources/org/jenkinsci/plugins/pipeline/modeldefinition/when/impl/EnvironmentConditional/help-name.html
pipeline-model-definition/src/main/resources/org/jenkinsci/plugins/pipeline/modeldefinition/when/impl/EnvironmentConditional/help-value.html
pipeline-model-definition/src/main/resources/org/jenkinsci/plugins/pipeline/modeldefinition/when/impl/EnvironmentConditional/help.html
pipeline-model-definition/src/main/resources/org/jenkinsci/plugins/pipeline/modeldefinition/when/impl/ExpressionConditional/help.html
pipeline-model-definition/src/main/resources/org/jenkinsci/plugins/pipeline/modeldefinition/when/impl/NotConditional/help.html
http://jenkins-ci.org/commit/pipeline-model-definition-plugin/7b7a3c75545666fd086f1a3317e4a750d6dff8dd
Log:
Add help HTML for user-facing Describables
This will help enable INFRA-1053 (auto-generation of help for
Declarative directives, like the step documentation on jenkins.io).
So three years later we still don't have all parameters documented. Can we have at least an manual documentation of the parameters please?
Would be great for this to work, since declarative pipeline is already deprecating the use of properties
Any news on that?
As Fabian said:
>Can we have at least an manual documentation of the parameters please?
Seriously, I have wasted hours and hours trying to figure out what the heck the syntax and options are for a variety of plugins and calls in declarative pipelines. The documentation is horrendously bad across the board. 4 years and counting.
Ive spend days trying to understand the documentation on how to create gerrit triggered multibranch jobs. Its impossible to find any answer.
The pipeline docs are pushing me to evaluate alternative tools.
Jenkins is a volunteer project. Almost every page on jenkins.io has a "Improve this page" link on the bottom, and is open to contributions. Otherwise the few people dedicated to documentation will prioritize as they feel fit. I'm sure you can find a contractor who would love to help out if they are paid.
I would recommend using the pipeline syntax generator, which is on the sidebar of your jenkins installation (I think only when your on a job).
Also I don't think the INFRA JIRA project is monitored by the jenkins.io team (they tend to use the github issue tracker linked at the bottom of every page), and such a broad topic of "Document everything" will never be completed.
In addition its up to individual plugin authors to document their plugins. If you see a plugin that doesn't have docs you like, you can open a ticket with them, or contribute some docs.
Closing as not an actual topic:
- https://www.jenkins.io/doc/book/pipeline/syntax/#options lists declarative possible options (at least the "common" one as some could be provided by some plugins)
- The snippet generaotr provides the exhaustive list, on your controllers, of available options
- This topic is outside infra's scope: either it should be a community.jenkins.io discussion or a topic to be brought to the "Special Interest Group" documentation as described in https://www.jenkins.io/sigs/docs/
Issue transfered in doc repository and reopened.
What is the reason to reopen it? Is there something missing in the actual doc?
Discussing with @MarkEWaite about it he asked me to move this issue here so it could be discussed from a doc point of view.
Issue transfered in doc repository and reopened.
What is the reason to reopen it? Is there something missing in the actual doc?
We have the automatically generated Pipeline Steps Reference . We don't have automatically generated documentation for declarative steps. I asked that this be moved to the jenkins.io repository and reopened so that we would have a location to track progress generating declarative Pipeline step documentation automatically.
The Pipeline Syntax page is the preferred location for declarative step documentation now, but it is not available inside the running Jenkins instance and is not extracted from the plugin source code, so it may not match with the current implementation. Readers that want to improve that page are encouraged to do so, but I wanted this issue to consider the addition of a new resource "Declarative Pipeline Steps Reference" at the same level as the current "Pipeline Steps reference".
@abayer as part of this issue you created a new repository https://github.com/jenkins-infra/pipeline-metadata-utils/commit/20145cf529d027ba97e430ba6713204a5e172ccf -- but then the declarative step generator was added to the pipeline doc generator so I'm wondering if that separate repo still makes sense?
thanks for the information, it looks like required is not supported anymore
