ANN: Support of plugin docs from GitHub on plugins.jenkins.io (WEBSITE-406)

[Oleg Nenashev]

Dear all,

We would like to announce support of GitHub README files as a documentation source for plugins.jenkins.io. Some examples of the documentation from GitHub:

• https://plugins.jenkins.io/configuration-as-code 
• https://plugins.jenkins.io/mailer 
• https://plugins.jenkins.io/folder-auth     

Why? This is a long-anticipated feature, many plugins have already moved their documentation to GitHub. By supporting such source in plugin site we provide good user experience to Jenkins users who look for documentation. At the same time, plugin maintainers now can follow the documentation-as-code approach and make documentation changes a part of the pull requests. It also gives an opportunity to review the documentation changes and to add documentation contributor recognition, especially if the story is combined with Release Drafter. 

 

The story is tracked as WEBSITE-406 which is a part of the wider subproject for supporting GitHub-based documentation in the Jenkins plugin site and update managers (WEBSITE-637 under the umbrella of the Documentation SIG). Later steps include support showing changelogs from GitHub releases, showing plugin logos. 

Current state. GitHub documentation source support is a new feature, early adopters are welcome to try it out. There might be defects we have not discovered yet, and it is yet to be seen how it scales. The implementation uses a GitHub application token to get a high API limit, and we also use https://www.jsdelivr.com/ as a CDN for images. If you hit any issue, please file a ticket in the WEBSITE-637 EPIC.  

How to enable GitHub documentation for your plugin? 

• Move documentation from Wiki to GitHub README if you have not done it yet. Both Markdown and Asciidoc are supported
• Change the <url> field in pom.xml so that it points to GitHub (example PR)
• Release a new plugin version
• Wait for few hours till the change gets propagated

Code? If you want to see the changes under the hood of the plugin site, please see the links in Plugin Site API v1.6.0 (yes, now we have changelog there!). So far we needed only the backend changes to add the feature, but there will be front-end changes for other stories inside the EPIC. If you are a Java or JavaScript/React developer, any contributions will be appreciated. The plugin site is really easy to develop.

Credits. I would like to thank Zbynek Konecny and Olivier Vernin for their work on these stories. They have done the vast majority of changes to make it happen.

If you have any questions/feedback, please do not hesitate to answer in this thread or to join the https://gitter.im/jenkinsci/docs chat. We will also have sync-ups and demos at the regular Documentation SIG meetings.

Best regards,

Oleg Nenashev

[Matt Sicker]

Great news!

> --
> You received this message because you are subscribed to the Google Groups "Jenkins Developers" group.
> To unsubscribe from this group and stop receiving emails from it, send an email to jenkinsci-de...@googlegroups.com.
> To view this discussion on the web visit https://groups.google.com/d/msgid/jenkinsci-dev/CAPfivLAKuSVR7cO-W%2BfXqe2K0BBsm8qa-38Arb-9Do32UHNDXg%40mail.gmail.com.



--
Matt Sicker
Senior Software Engineer, CloudBees

[Rick]

Awesome feature!

To view this discussion on the web visit https://groups.google.com/d/msgid/jenkinsci-dev/CAEot4ox_VA5Uyy2XN%3Df75xC07Z_CY3%3Dxjm3cXRjA_b1vdE59PA%40mail.gmail.com.

--

Zhao Xiaojie (Rick)

Blog: https://github.com/LinuxSuRen

Twitter: https://twitter.com/suren69811254

[Gavin Mogan]

Just so I understand, as I was kinda confused, https://plugins.jenkins.io/folder-auth is showing content because its pulling from github's README.md

Checking https://plugins.jenkins.io/folder-auth i can see https://wiki.jenkins.io/display/JENKINS/Folder+Authorization+Plugin is quite empty, so that makes sense.

I was very confused cause release logs kept being mentioned.

To view this discussion on the web visit https://groups.google.com/d/msgid/jenkinsci-dev/CAMM7nTFdtSin_SFeop25Pr0Sas%2BXgXzubapiZgEMvRY9c6nZcA%40mail.gmail.com.

[Oleg Nenashev]

Hi Gavin,

I was very confused cause release logs kept being mentioned.

Release logs are generally not supported by the plugin site.There is a task to support CHANGELOG.md and GitHub Releases in WEBSITE-637, but it is yet to be implemented

Current state for changelogs:

• If you publish Wiki documentation and keep changelog in Wiki and , it will be displayed on the plugin site. E.g. https://plugins.jenkins.io/cvs
• If you publish GitHub documentation and keep changelog in README, it will be displayed on the plugin site. No example ATM
• If you publish GitHub documentation and reference changelogs from README (badges or in text), the references will be displayed
• Badges example: https://plugins.jenkins.io/configuration-as-code
• Text example: https://plugins.jenkins.io/mailer (scroll to the bottom)
• If you publish GitHub documentation and just use GitHub releases or CHANGELOG.md without referencing them from readme, there will be no reference to changelog from the site
• Example: https://plugins.jenkins.io/folder-auth (I will fix it today)
• Users will need to navigate to GitHub to see the links to changelog

My plan is to eventually use the logic similar to how Dependabot displays changelogs in pull requests. Maybe even by reusing the Dependabot library in the Plugin Site backend or whatever changelog crawler.

Please let me know if it answers your question.

Best regards,

Oleg

On Wednesday, September 4, 2019 at 1:58:15 AM UTC+2, Gavin Mogan wrote:

Just so I understand, as I was kinda confused, https://plugins.jenkins.io/folder-auth is showing content because its pulling from github's README.md

Checking https://plugins.jenkins.io/folder-auth i can see https://wiki.jenkins.io/display/JENKINS/Folder+Authorization+Plugin is quite empty, so that makes sense.

I was very confused cause release logs kept being mentioned.

On Tue, Sep 3, 2019 at 4:46 PM Rick <linux...@gmail.com> wrote:

Awesome feature!

On Wed, Sep 4, 2019 at 5:58 AM Matt Sicker <msi...@cloudbees.com> wrote:

Great news!

On Tue, Sep 3, 2019 at 4:18 PM Oleg Nenashev <o.v.n...@gmail.com> wrote:
>
> Dear all,
>
> We would like to announce support of GitHub README files as a documentation source for plugins.jenkins.io. Some examples of the documentation from GitHub:
>
> https://plugins.jenkins.io/configuration-as-code
> https://plugins.jenkins.io/mailer
> https://plugins.jenkins.io/folder-auth
>
> Why? This is a long-anticipated feature, many plugins have already moved their documentation to GitHub. By supporting such source in plugin site we provide good user experience to Jenkins users who look for documentation. At the same time, plugin maintainers now can follow the documentation-as-code approach and make documentation changes a part of the pull requests. It also gives an opportunity to review the documentation changes and to add documentation contributor recognition, especially if the story is combined with Release Drafter.
>
> The story is tracked as WEBSITE-406 which is a part of the wider subproject for supporting GitHub-based documentation in the Jenkins plugin site and update managers (WEBSITE-637 under the umbrella of the Documentation SIG). Later steps include support showing changelogs from GitHub releases, showing plugin logos.
>
> Current state. GitHub documentation source support is a new feature, early adopters are welcome to try it out. There might be defects we have not discovered yet, and it is yet to be seen how it scales. The implementation uses a GitHub application token to get a high API limit, and we also use https://www.jsdelivr.com/ as a CDN for images. If you hit any issue, please file a ticket in the WEBSITE-637 EPIC.
>
> How to enable GitHub documentation for your plugin?
>
> Move documentation from Wiki to GitHub README if you have not done it yet. Both Markdown and Asciidoc are supported
> Change the <url> field in pom.xml so that it points to GitHub (example PR)
> Release a new plugin version
> Wait for few hours till the change gets propagated
>
> Code? If you want to see the changes under the hood of the plugin site, please see the links in Plugin Site API v1.6.0 (yes, now we have changelog there!). So far we needed only the backend changes to add the feature, but there will be front-end changes for other stories inside the EPIC. If you are a Java or JavaScript/React developer, any contributions will be appreciated. The plugin site is really easy to develop.
>
> Credits. I would like to thank Zbynek Konecny and Olivier Vernin for their work on these stories. They have done the vast majority of changes to make it happen.
>
> If you have any questions/feedback, please do not hesitate to answer in this thread or to join the https://gitter.im/jenkinsci/docs chat. We will also have sync-ups and demos at the regular Documentation SIG meetings.
>
> Best regards,
> Oleg Nenashev
>
> --
> You received this message because you are subscribed to the Google Groups "Jenkins Developers" group.

> To unsubscribe from this group and stop receiving emails from it, send an email to jenkin...@googlegroups.com.

> To view this discussion on the web visit https://groups.google.com/d/msgid/jenkinsci-dev/CAPfivLAKuSVR7cO-W%2BfXqe2K0BBsm8qa-38Arb-9Do32UHNDXg%40mail.gmail.com.



--
Matt Sicker
Senior Software Engineer, CloudBees

--
You received this message because you are subscribed to the Google Groups "Jenkins Developers" group.

To unsubscribe from this group and stop receiving emails from it, send an email to jenkin...@googlegroups.com.

To view this discussion on the web visit https://groups.google.com/d/msgid/jenkinsci-dev/CAEot4ox_VA5Uyy2XN%3Df75xC07Z_CY3%3Dxjm3cXRjA_b1vdE59PA%40mail.gmail.com.

--

Zhao Xiaojie (Rick)

Blog: https://github.com/LinuxSuRen

Twitter: https://twitter.com/suren69811254

--
You received this message because you are subscribed to the Google Groups "Jenkins Developers" group.

To unsubscribe from this group and stop receiving emails from it, send an email to jenkin...@googlegroups.com.

[Robert Sandell]

Finally!! Yay! :D

Would it be possible to have something other than the README.md? As I mentioned way back when the GSoC project that never finished, to me the README is more about the repository itself; what it is, how to build it etc. i.e. developer documentation. While user documentation should be something/somewhere else in the repo.

/B

To unsubscribe from this group and stop receiving emails from it, send an email to jenkinsci-de...@googlegroups.com.
To view this discussion on the web visit https://groups.google.com/d/msgid/jenkinsci-dev/199e5624-89ac-4e9d-b674-848d9c796efd%40googlegroups.com.

--

Robert Sandell

Software Engineer

CloudBees, Inc.

E: rsan...@cloudbees.com

Twitter: robert_sandell

[Oleg Nenashev]

Would it be possible to have something other than the README.md? As I mentioned way back when the GSoC project that never finished, to me the README is more about the repository itself; what it is, how to build it etc. i.e. developer documentation. While user documentation should be something/somewhere else in the repo. 

Yes, we could do so. We have several cases when the documentation is hosted on custom pages or on jenkins.io, and there are definitely some opportunities for custom sources. Moeover, if this engine is eve implemented, we could reuse it later to implement the GitHub => jenkins.io publishing later.

The easiest way would be to....

• Add a new "hpi.pluginDocumentationUrl" property to Maven HPI Plugin (similar to hpi.pluginChangelogUrl and hpi.pluginLogoUrl  in 3.8)
• Update Jenkins Update Center to take this property into account while generating plugin-documentation-urls JSON
• Update GitHubExtractor in Plugin Site API to properly process custom URLs. A new extractor might be required

 I have created https://issues.jenkins-ci.org/browse/WEBSITE-648 for it.

BR, Oleg

You received this message because you are subscribed to a topic in the Google Groups "Jenkins Developers" group.
To unsubscribe from this topic, visit https://groups.google.com/d/topic/jenkinsci-dev/VSdfVMDIW-A/unsubscribe.
To unsubscribe from this group and all its topics, send an email to jenkinsci-de...@googlegroups.com.
To view this discussion on the web visit https://groups.google.com/d/msgid/jenkinsci-dev/CALzHZS1ux03k%3DW-QWmoz6PMC70CWVF%2BTp9RcT3kONx%2B2h_g3Tw%40mail.gmail.com.

[Gavin]

Longer term too, it should probably be the actual git revision that was published, since master often contains changes that are not yet live.

To view this discussion on the web visit https://groups.google.com/d/msgid/jenkinsci-dev/CAPfivLAWWnWsHtGSSRhr6Lh6xhbdD-gKcewfrx_h%3DJihYFyDJQ%40mail.gmail.com.

[Oleg Nenashev]

Longer term too, it should probably be the actual git revision that was published, since master often contains changes that are not yet live.

https://issues.jenkins-ci.org/browse/WEBSITE-641 has been created for it a while ago. It would be a nice follow-up indeed

Anyway, the current behavior is pretty much like in Confluence.

 

To view this discussion on the web visit https://groups.google.com/d/msgid/jenkinsci-dev/CAG%3D_DutA4BPRjx%3DMrsZ%2BO2Rf5c04U0RQ75Dbk9zGcxsV9XC4_A%40mail.gmail.com.

[Oleg Nenashev]

Hi all,

Just few updates here:

• Over the last week 29 plugins were migrated to GitHub documentation sources. Some of them are waiting for release, but there is a good trend
• Few examples: Git, Git Client, JobDSL, Kubernetes, Gradle, Warnings NG, Role Strategy, Mailer, etc.
• There are example of migration to Gradle flow (e.g. here). It is also a one-line change for the url field in the jenkinsPlugin{} 
  closure from Gradle JPI Plugin
• There were few updates in documentation rendering since the announcement:
• There was a regression in Wiki rendering due t encoding issues. It was fixed by Zbynek in Plugin Site API v1.7.0
• When GitHub source is used, the header and extra padding are now truncated, so there is no double header on the plugin page. Thanks to Zbynek again!
• We added a "Links" tab to the right panel. Javadoc links have been added there. Later we will also add Changelog URLs, JIRA/GitHub issues links and other metadata which can be traversed from the repo
• There is ongoing work by Zbynek to add support of arbitrary GitHub URLs as documentation sources, not just README. See https://github.com/jenkins-infra/plugin-site-api/pull/69

BR, Oleg

To unsubscribe from this group and stop receiving emails from it, send an email to jenkinsci-dev+unsubscribe@googlegroups.com.

To view this discussion on the web visit https://groups.google.com/d/msgid/jenkinsci-dev/199e5624-89ac-4e9d-b674-848d9c796efd%40googlegroups.com.

--

Robert Sandell

Software Engineer

CloudBees, Inc.

E: rsan...@cloudbees.com

Twitter: robert_sandell

--
You received this message because you are subscribed to a topic in the Google Groups "Jenkins Developers" group.
To unsubscribe from this topic, visit https://groups.google.com/d/topic/jenkinsci-dev/VSdfVMDIW-A/unsubscribe.

To unsubscribe from this group and all its topics, send an email to jenkinsci-dev+unsubscribe@googlegroups.com.

To view this discussion on the web visit https://groups.google.com/d/msgid/jenkinsci-dev/CALzHZS1ux03k%3DW-QWmoz6PMC70CWVF%2BTp9RcT3kONx%2B2h_g3Tw%40mail.gmail.com.

--
You received this message because you are subscribed to the Google Groups "Jenkins Developers" group.

To unsubscribe from this group and stop receiving emails from it, send an email to jenkinsci-dev+unsubscribe@googlegroups.com.

To view this discussion on the web visit https://groups.google.com/d/msgid/jenkinsci-dev/CAPfivLAWWnWsHtGSSRhr6Lh6xhbdD-gKcewfrx_h%3DJihYFyDJQ%40mail.gmail.com.

--
You received this message because you are subscribed to a topic in the Google Groups "Jenkins Developers" group.
To unsubscribe from this topic, visit https://groups.google.com/d/topic/jenkinsci-dev/VSdfVMDIW-A/unsubscribe.

To unsubscribe from this group and all its topics, send an email to jenkinsci-dev+unsubscribe@googlegroups.com.