Jenkins : Automatic Plugin Documentation Publishing

Name : Cynthia Anyango

Email: acynthiaanyango@gmail.com

irc:     canyango

Country of residence: Kenya

Timezone: UTC +3

Synopsis

The Jenkins plugin ecosystem is large and decentralized, which is great for open source developers but difficult to interact with as a user of Jenkins. The problem to be solved is: how do we centralize documentation for Jenkins users, while respecting decentralized plugin development.

I have had discussions with R.Tyler Croy who is the project mentor about how scattred plugin documentations really are .  There are couple of suggestions that had been put up by the team , they include :

  • “Big bang” - moving  all the plugins from the wiki to the static site(which is just not realistic)
  • plugin pages could pull in some contents from outside, such as Git repo README
  • Automatically pulling in the README from GitHub, shows changelogs with versions and releases dates, and (presumably) pulls that in from GitHub too

Benefits to Community

  • This project will benefit the general open source  community which uses Jenkins , by ensuring that Jenkins  documentation is centralized, easy to find and up to date.
  • Encourage plugin developers to commit documentation changes alongside their code changes which helps keep documentation current
  • Plugin documentation will be easily contributed to for new and existing users via GitHub

Deliverables

  1. Gather plugin sources## See the backend-merge-all-repos project, Tyler to make sure an “all.git” is available for processing
  2. Define basic plugin developer documentation conventions## README.adoc, md required## CHANGELOG.adoc, md required
    1. Additional documentation file, e.g. TUTORIAL.md, COMPATIBILITY.md, etc
  3. Prototype with friendly/willing plugin maintainers## E.g. autojack, orrc, batmat, olegnenashev, danielbeck,slide_o_mix
  4. Incorporate basic plugin documentation structure into site## Preparing a plugin subsection in the “Documentation” area## Representing “additional docs” in a navigable way for users
    1. Providing a clear “Plugin Homepage” (ensure we have the plugin ID at build time)
  5. Get agreement among plugin developers## Proposal sent to dev list## Governance meeting agenda item
  6. BONUS: Provide mechanism for plugin developers to define richer metadata to incorporate into the site, such as “Getting Started” steps, youtube videos, or anything else that can be used to render in exisitng UI elements (see http://beta.jenkins.io/solutions/docker for an example)
  7. Update jenkins.io build/release process to properly generate the site with plugin documentation

Project plan

22 April – 22 May

Community Bonding.
Learn more about Jenkins , awestruct , pipeline , ask the mentors and the community lots of questions

23 May – 1st June

Gather plugin sources

2nd June  -- 16 June

Define basic plugin developer documentation conventions

17 June – 23 June

Prototype with friendly/willing plugin maintainers

23 June – 27 June

Preparation and submission of midterm evaluation

23 June – 1st July

Finish up prototyping

2nd July – 14th July

Incorporate basic plugin documentation structure into site

15th July - 23rd July

Get agreement among plugin developers

24t July - 3rd July

Update jenkins.io build/release process to properly generate the site with plugin documentation

1st July - 7th August

OptionalProvide mechanism for plugin developers to define richer metadata to incorporate into the site

1st July - 7th August

  • Write documentation for the code
  • Tidy code
  • Clean up files and remove useless code
  • Add relevant comments to the ruby code.
  • Work on any bug

August 15 - 23, 2016

Submit Code