Pipeline Step Documentation Generator improvements

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

Skills to study/improve: Java, Jenkins Pipeline, HTML, CSS, Asciidoc, JavaScript

Details

Background

The Jenkins Pipeline Step reference is difficult to read, even to the initiated, mostly due to its format. This project aims to improve the way the documentation is formatted.

For example, when you read the readFile step documentation, the documentation format makes it difficult to see that the obvious usage is : readFile('filename'). When you read the checkout documentation, you are shown a single web page with collapsible sections that when expanded and printed would be 62 pages long. That is too large a page for usable navigation. We should consider logical partitions of that page, possibly with a single page per SCM provider (like checkout-git, checkout-p4, checkout-svn, checkout-cvs). Redirects would be needed within the checkout page to link users to the correct page per SCM provider.

Quick Start Guide

For this project, the student is expected to study the documentation generator code base, the documentation feedback from readers, and to propose enhancements to the documentation generator code to improve the format, layout, and readability of the documentation published on-line. The student is not expected to contribute to the content of the documentation, however, technical additions that enhance the discoverability of the documentation via annotations or other special markup are considered valid for a coding project.

Many of the Pipeline step references include no documentation. Those pages could have a standard reference created that directs the reader to use the Pipeline Syntax snippet generator. See the git plugin documentation for one idea of a way to encourage use of the snippet generator.

The student is also expected to study Stapler and Jelly, as these technologies are used to capture documentation as well. Documentation can be extracted from Stapler and Jelly.

A potential stretch goal could be something like an embedded pipeline steps generator, though that might be outside the scope of the website.

Examples of remote documentation:

  • Pipeline: AWS steps adds documentation to the README

  • JIRA Pipeline steps keeps their documentation in their repo, and displays it as a weblink.

Project Difficulty Level

Beginner to Intermediate

Project Size

175 hours

Expected outcomes

Improvement of existing tool and documentation generated by the tool.

Jenkins Pipeline step documentation will be presented in a more usable and readable format. Pipeline step documentation will be partitioned into smaller pages for better access by users. Pipeline step documentation will be better formatted so that users are more likely to find the information they are seeking.

Newbie Friendly issues

Potential Mentors

Project Links

Organization Links

> Go back to other GSoC 2022 project ideas