Reference documentation for JCasC YAML

Hi, I very appreciate the JCasC project and your ongoing work here (or related like https://jenkins.io/projects/jcasc/dev-tools/)

You, as insiders, might be fine with the demos as documentation and with the tests on them. But I mean for many developers it takes too much time to find an answer to simple questions, arising when trying to use JCasC, for instance:

• Jenkins officially supports SSH connected agents (https://hub.docker.com/r/jenkins/ssh-slave), but nothing is to find how this could be addressed in JCasC, let alone a list of the supported keys and values in the YAML tree; only java tests hint

  agentProtocols:
      - "JNLP4-connect"
      - "Ping"
  

• Is the JCasC root section plugins still relevant? (As for the chicken-egg problem an earlier RUN /usr/local/bin/install-plugins.sh < /usr/share/jenkins/ref/plugins.txt is needed anyway.)
• Are the PNGs with these limited options trees meant to be the documentation?

⇒

As a developer trying to achieve an end-to-end CI/CD, based on configuration-as-code, I would like to avoid scripted configuration via Groovy or Python, but to find

• a (generated!) reference documentation for JCasC YAML with all relevant options listed and explained (like https://jenkinsci.github.io/job-dsl-plugin/)
• a wiki summarizing the best-practices for frequent standard use cases and frequent stumble stones (similar to https://github.com/jenkinsci/job-dsl-plugin/wiki),

This relates to, but is not covered by #1037 and #1216.

Regards, Tom

[damarvin]

Joseph, Thanks a lot for the fast response.

Cool feature (always up-to-date), when plugins like Job-DSL or JCasC document themselves in a running system, but you should find it w/o bothering forums 😛

I scrolled through this several times and wondered which page

“Click the Documentation link at the bottom of the Configuration as Code page.”

may refer too.

So could you please replace this sentence at Initial Configuration by something more precise like

To see the Jenkins Master reference documentation go to Manage Jenkins > Configuration as Code > Documentation. There you can also export or View Configuration.

(and change the label of #1242 to “documentation” — there wasn’t a button for me)?

Your hint “This is partly covered by JSON schema too: #1076” might be correct, but me and others searching for YAML documentation and using another IDE would not expect to find the reference documentation under “JSON schema and VC Code”. Again, here you probably mean the running system http://YOUR_JENKINS:8080/configuration-as-code/.

As I can view my Jenkins Master JCasC YAML now, I’m fine. With a small change like proposed above this could be closed.

[stale[bot]]

This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs. Thank you for your contributions.