Jenkins.io is generated as a static web site from asciidoc sources stored in GitHub. One of the drawback of the current build method is that the technical documentation is not product version bound. It is thus not possible to view the documentation for a given Jenkins version. Only the latest can be viewed. This can lead to unnecessary confusion.
Two tools are currently looked at whether they can solve the requirement, while keeping the existing functionalities and automation: Hugo and Antora.
The potential GSoC project(s) would be to build a working tooling to generate the site in its existing form and to demonstrate the new documentation requirement.
Based on these implementations (Hugo or Antora based), the Community would choose which path to go for the modernization of Jenkins.io.
The deliverables of the project(s) would be:
fully automated (CI ready) build procedure, equivalent to the existing one
demonstration that all the existing pages are rendered in an equivalent way
suggestion of improved page design
list of all automation that are difficult/impossible to port to the new tool
suggestions and demos of alternative ways to solve this.
demonstration of the versioned documentation
automated tooling
description of the publication process (how does one contribute to document a new or modified feature)
Would this be an interesting project for GSoC participants and for the Community?
I wonder how Hugo fits into this? Didn’t know Antora before but this seems to be designed to do more or less what we might want here.
By the way, PostgreSQL documentation has issues explaining to the search engines which is the newest version of the documentation. By doing simple search one usually gets links to older versions or a confusing mix of old and new stuff.
@reveurguy The idea is still under discussion and we cannot assign anyone to work on it at the moment. There will be more details about this project coming up over the next few weeks. The decision of who will be working on the idea for GSoC will be decided by a selection process that will take place in the Spring of 2023. So stay tuned if you are interested.
Yeah @saper I have been wondering how relevant Hugo is for this type of work myself as well, while Antora seems to offer the perfect fit as a tool for what we will need in the project.
Hi, I am interested in mentoring the project Building Jenkins.io with alternative tools. I am also open to being a co-mentor. I am also open to being a co-mentor. As an open-source enthusiast, I have completed the following programs: GSoC 2022 with Keptn, LFX Mentorship Fall 2021 with moja global, GSoD 2021 with Wechaty, and GSoD 2020 with gRPC-Gateway.
Hi, I have already worked on creating a documentation site for Keptn as part of my GSoC 2022 project. We were building a New Documentation Site Engine. I also did a comparison of Antora and Docusaru, which can be found here. Maybe we can take reference from the project I did for Keptn during GSoC 2022.
@iamrajiv Actually we have already decided to use Antora since it offers the most direct setup we need. We do not want to convert the existing docs to Markdown, as that would introduce an extra layer of complexity, which is exactly the reason why we would not consider using Docusaurus.
Got it, @krisstern. So the plan for implementing this is to create the framework for the documentation site using Antora and then transfer the content from the current documentation site to Antora, is that correct?
@iamrajiv Yup, but it is more than that. So bascially we will need to replace the exising tool called Awestruck with Antora, and to add documentation versioning with this new tool, plus there is expected to be some improvements to the current site and page layouts.
The thing is this project has many parts so can get complicated as a proof-of-concept. We may push it to be adopted eventually but that will take some liaising and management work.
Got it, @krisstern. So, we need to set up a new project using Antora. Should this be done in a separate repository, in a new branch of the existing jenkins.io repository, or in a personal repository?
@iamrajiv I think the contributor will need to set up a new branch to replicate the existing website first. For the running of the jenkins.io website we are using Docker to the best of my knowledge.