Api Viewer for DSL contributed by other plugins

[Stefan Wolf]

Hi,

recently, the documentation was changed to use an API-Viewer which shows the generated documentation for the DSL-Elements of the job dsl plugin. Since it is now also possible to contribute to the DSL by using an extension point from another plugin I would like to know if there is already a possibility to generate the documentation for this external plugin or even better show all the documentation in one place.

The implementation of the Extension point I did is here: https://github.com/jenkinsci/jgiven-plugin/blob/master/src/main/java/org/jenkinsci/plugins/jgiven/JgivenDslContextExtension.java

Regards,

Stefan

[Daniel Spilker]

Hi,

I have not thought about integrating documentation from extension points into the API viewer. But for a start, we could link to plugins which implement the extension point on the API Viewer home page (https://jenkinsci.github.io/job-dsl-plugin/, https://github.com/jenkinsci/job-dsl-plugin/blob/master/job-dsl-api-viewer/src/templates/home.hbs) and the plugin documents its DSL API on its wiki page. Exactly like you did: https://wiki.jenkins-ci.org/display/JENKINS/JGiven+Plugin#JGivenPlugin-JobDSL.

Daniel

--
You received this message because you are subscribed to the Google Groups "job-dsl-plugin" group.
To unsubscribe from this group and stop receiving emails from it, send an email to job-dsl-plugi...@googlegroups.com.
To post to this group, send email to job-dsl...@googlegroups.com.
To view this discussion on the web visit https://groups.google.com/d/msgid/job-dsl-plugin/89936a3d-b582-40fd-879b-300df4e9ffbe%40googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

[Stefan Wolf]

Wouldn't it be possible that my plugin generates the json-files for the API-Viewer and then the API-Viewer loads this json-file, too and displays it?

What would need to be done for this to work?

Regards,

Stefan

[Daniel Spilker]

OK, so we need a class with a main method to generate the JSON. That class can be run using the maven-exec-plugin or a Gradle exec tasks. It needs to auto-detect the ContextExtensionPoints or they must be specified as arguments.

The Job DSL API JSON file is uploaded to the Jenkins repo, e.g. http://repo.jenkins-ci.org/releases/org/jenkins-ci/plugins/job-dsl-core/1.38/job-dsl-core-1.38-apidoc.json. JSON files from other plugins should be uploaded as well. The API viewer Gradle/Gulp build can then download all JSON files.

Currently the API viewer will get updated when a new Job DSL version is released, that would mean that API for other plugins will only show up after Job DSL has been released. Would that be OK?

The API viewer has a version selector for the Job DSL API. Does it need a selector for each plugin API? Or should it just show the latest version for plugins?

Daniel

To view this discussion on the web visit https://groups.google.com/d/msgid/job-dsl-plugin/857aed18-bc02-408d-805a-e19ba4c49e5d%40googlegroups.com.

[Daniel Spilker]

For 1.39, I put a link to the JGiven plugin on the API viewer home page. But we should keep thinking about an integration for future releases.

[Daniel Spilker]

I have some more thoughts about this. How about packaging the API viewer (in addition to the online version) into the Job DSL plugin and serve the pages through Jenkins? Assuming we have the JSON, the Job DSL plugin and each plugin implementing the extension point could ship the JSON in the HPI file. The integrated API viewer could than show the API for the installed plugin version. There would be no need for a version selector and even the plugin filter could be pre-populated. My (naive) assumption would be that this would require only minor changes to the API viewer and we could build both versions (online and integrated) from the same source.

Stefan, Matt, what do you think?

Daniel

[Stefan Wolf]

Sounds like a good idea to me.

[Matt Sheehan]

That would be cool. How would you find the json files? Also do you know of a plugin doing something similar I could take a look at?

To view this discussion on the web visit https://groups.google.com/d/msgid/job-dsl-plugin/7c7077c4-9255-4f6b-8be8-3a44f1289f0f%40googlegroups.com.

[Daniel Spilker]

I've been working on the embedded API viewer. As a first step it will be able to show method signatures for every @DslExtensionMethod, but not nested contexts. But there will be a link to the implementing plugin's wiki page which will hopefully show DSL details.

See https://github.com/jenkinsci/job-dsl-plugin/pull/829. Can someone give it a try or do a review?

Daniel

To unsubscribe from this group and stop receiving emails from it, send an email to job-dsl-plugin+unsubscribe@googlegroups.com.
To post to this group, send email to job-dsl-plugin@googlegroups.com.