Uploaded image for project: 'Infrastructure'
  1. Infrastructure
  2. INFRA-1053

Generate automated documentation for options/parameters in Declarative Pipeline

    Details

    • Similar Issues:

      Description

      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 <plugin name>
      • Parameters
      • ???

        Attachments

          Issue Links

            Activity

            Hide
            abayer Andrew Bayer added a comment -

            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.

            Show
            abayer Andrew Bayer added a comment - 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.
            Hide
            jshumaker Jody Shumaker added a comment -

            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:

            https://github.com/jenkinsci/job-dsl-plugin/blob/master/job-dsl-core/src/main/groovy/javaposse/jobdsl/dsl/helpers/BuildParametersContext.groovy

            Show
            jshumaker Jody Shumaker added a comment - 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: https://github.com/jenkinsci/job-dsl-plugin/blob/master/job-dsl-core/src/main/groovy/javaposse/jobdsl/dsl/helpers/BuildParametersContext.groovy
            Hide
            jedavis Jason Davis added a comment -

            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
                        }    
                    }        
                }
            }
            
            Show
            jedavis Jason Davis added a comment - 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 } } } }
            Hide
            gnuhchnim Minh Chung added a comment -

            Is the GIT Parameters plugin supported for the pipeline jenkinsfile declarative?

            Show
            gnuhchnim Minh Chung added a comment - Is the GIT Parameters plugin supported for the pipeline jenkinsfile declarative?
            Hide
            invsblduck Brett Campbell added a comment -

            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.

            Show
            invsblduck Brett Campbell added a comment - 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.
            Hide
            abayer Andrew Bayer added a comment -

            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.

            Show
            abayer Andrew Bayer added a comment - 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.
            Hide
            abayer Andrew Bayer added a comment -

            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.

            Show
            abayer Andrew Bayer added a comment - 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.
            Hide
            abayer Andrew Bayer added a comment -

            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.

            Show
            abayer Andrew Bayer added a comment - 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.
            Hide
            scm_issue_link SCM/JIRA link daemon added a comment -

            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).

            Show
            scm_issue_link SCM/JIRA link daemon added a comment - 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).

              People

              • Assignee:
                abayer Andrew Bayer
                Reporter:
                rtyler R. Tyler Croy
              • Votes:
                32 Vote for this issue
                Watchers:
                36 Start watching this issue

                Dates

                • Created:
                  Updated: