Pipeline Step Documentation Generator improvements

Goal: Enhance the Jenkins Pipeline documentation generator to produce better documentation for thousands of Pipeline developers

Status: Selected

Team

Details

Abstract

This project aims to improve the Pipeline Steps Reference that is generated automatically with the help of the plugin manager associated with a mock Jenkins instance. The improvements will lead to a smoother user experience and better usability of the generated documentation.

Rationale

Documenting the Pipeline steps is not an easy task. Currently, there are more than 600 plugins that provide 1500+ steps for use within a Pipeline script. Furthermore, these steps have several parameters that may be used along with them. All these steps are documented in the Asciidoc format, which is autogenerated in a specified format by a Java program.

Although the Pipeline Snippet Generator is the best way to understand how a step should be used, there are two reasons why documenting all the steps is necessary.

  1. Not all users are aware of how the snippet generator works.

  2. There must be a compilation of all the steps available across all the plugins.

So, to work with documentation of this magnitude, it is required that we generate and format it so that the user can find the piece of information they are seeking effectively. Thousands of Pipeline developers all over the world will benefit from improvements in the same.

Implementation

The implementation revolves around two major changes.

  1. Changes to jenkins.io - Change the navigation experience on the website. This includes changing the behaviour of the sidebar and adding a search feature on the Pipeline Steps reference page.

  2. Changes to pipeline-step-docs-generator - Format the parameter details in a better way and ensure that the plugin pages with large (and sometimes redundant) content are made more lightweight to facilitate faster loading.

  3. Releasing pipeline-metadata-utils - This artifact will contain a HyperLocalPluginManager class that can be used to initialize a jenkins instance with the plugins, which can then be queried for a varied set of information.

Apart from these changes, minor changes will be done to refactor the code and remove anomalies from the steps documentation.

Office Hours

Links