[HSEARCH] Provide multiple getting started guides

yrodiere · marko-bekhta · commit bff6e709037e · 2024-10-04T10:41:41.000+02:00
diff --git a/_config/site.yml b/_config/site.yml
@@ -193,8 +193,12 @@ projects:
         latest_stable:
           html: https://docs.jboss.org/hibernate/stable/search/api/
       getting_started_guide:
-        html: https://docs.jboss.org/hibernate/search/{series.version}/getting-started/orm/en-US/html_single/
-        pdf: https://docs.jboss.org/hibernate/search/{series.version}/getting-started/orm/en-US/pdf/hibernate_search_getting_started_orm.pdf
+        - name: ORM
+          html: https://docs.jboss.org/hibernate/search/{series.version}/getting-started/orm/en-US/html_single/
+          pdf: https://docs.jboss.org/hibernate/search/{series.version}/getting-started/orm/en-US/pdf/hibernate_search_getting_started_orm.pdf
+        - name: Standalone
+          html: https://docs.jboss.org/hibernate/search/{series.version}/getting-started/standalone/en-US/html_single/
+          pdf: https://docs.jboss.org/hibernate/search/{series.version}/getting-started/standalone/en-US/pdf/hibernate_search_getting_started_standalone.pdf
       migration_guide:
         html: https://docs.jboss.org/hibernate/search/{series.version}/migration/html_single/
         pdf: https://docs.jboss.org/hibernate/search/{series.version}/migration/pdf/hibernate_search_migration.pdf
diff --git a/_ext/links.rb b/_ext/links.rb
@@ -16,8 +16,8 @@ def javadoc(project, series)
         return DocumentRef.from_patterns(project, series, :javadoc)
       end
 
-      def getting_started_guide(project, series)
-        return DocumentRef.from_patterns(project, series, :getting_started_guide)
+      def getting_started_guides(project, series)
+        return DocumentRef.from_patterns_multi(project, series, :getting_started_guide)
       end
 
       def migration_guide(project, series)
@@ -148,13 +148,32 @@ class DocumentRef
 
         def self.from_patterns(project, series, link_key)
           log_prefix = "#{project.name}/#{series.version}/#{link_key}: "
-          link = series&.links&.[](link_key)
-          link ||= project&.links&.[](link_key)
+          link_root = series&.links&.[](link_key)
+          link_root ||= project&.links&.[](link_key)
+          return from_patterns_single(project, series, link_key, link_root)
+        end
+
+        def self.from_patterns_multi(project, series, link_key)
+          log_prefix = "#{project.name}/#{series.version}/#{link_key}: "
+          link_root = series&.links&.[](link_key)
+          link_root ||= project&.links&.[](link_key)
+          links = []
+          if link_root.kind_of?(Array)
+            link_root.each do |link|
+              links.push(from_patterns_single(project, series, link_key, link))
+            end
+          else
+            links.push(from_patterns_single(project, series, link_key, link_root))
+          end
+          return links.compact
+        end
+
+        def self.from_patterns_single(project, series, link_key, link)
+          log_prefix = "#{project.name}/#{series.version}/#{link_key}: "
           if link.nil?
             @@logger.debug("#{log_prefix}Link is nil")
             return nil
           end
-          @@logger.debug("#{log_prefix}Link is #{link}")
           displayed = link['displayed']
           if not displayed.nil? and not displayed
             @@logger.debug("#{log_prefix}Link is not displayed")
@@ -165,6 +184,8 @@ def self.from_patterns(project, series, link_key)
             @@logger.debug("#{log_prefix}Link is for the latest stable series only")
             return nil
           end
+          name = link['name']
+          @@logger.debug("#{log_prefix}Link name: #{name}")
           latest_stable = link['latest_stable']
           if latest_stable and series.latest_stable
             link = latest_stable
@@ -179,12 +200,13 @@ def self.from_patterns(project, series, link_key)
           if html_url.nil? and pdf_url.nil?
             return nil
           end
-          return DocumentRef.new(html_url, pdf_url)
+          return DocumentRef.new(name, html_url, pdf_url)
         end
 
-        attr_reader :html_url, :pdf_url
+        attr_reader :name, :html_url, :pdf_url
 
-        def initialize(html_url, pdf_url)
+        def initialize(name, html_url, pdf_url)
+          @name = name
           @html_url = html_url
           @pdf_url = pdf_url
         end
diff --git a/_layouts/project/project-documentation.html.haml b/_layouts/project/project-documentation.html.haml
@@ -47,11 +47,12 @@ project_buttons_partial: project/documentation-buttons.html.haml
             %a.ui.right.labeled.icon.button.small(href="#{javadoc.html_url}")
               %i.icon.code.outline
               API (JavaDoc)
-          - getting_started_guide = getting_started_guide(project_description, series)
-          - if not getting_started_guide.nil?
+          - getting_started_guides(project_description, series).each do |getting_started_guide|
             %p
               %span.ui.label.basic.horizontal
                 Getting started guide
+                - if getting_started_guide.name
+                  = "(#{getting_started_guide.name})"
               - if not getting_started_guide.html_url.nil?
                 %a.ui.right.labeled.icon.button.small(href="#{getting_started_guide.html_url}")
                   %i.icon.file.text.outline
@@ -124,11 +125,12 @@ project_buttons_partial: project/documentation-buttons.html.haml
               %a.ui.right.labeled.icon.button.small(href="#{javadoc.html_url}")
                 %i.icon.code.outline
                 API (JavaDoc)
-            - getting_started_guide = getting_started_guide(project_description, series)
-            - if not getting_started_guide.nil?
+            - getting_started_guides(project_description, series).each do |getting_started_guide|
               %p
                 %span.ui.label.basic.horizontal
                   Getting started guide
+                  - if getting_started_guide.name
+                    = "(#{getting_started_guide.name})"
                 - if not getting_started_guide.html_url.nil?
                   %a.ui.right.labeled.icon.button.small(href="#{getting_started_guide.html_url}")
                     %i.icon.file.text.outline
diff --git a/_layouts/project/project-getting-started.html.haml b/_layouts/project/project-getting-started.html.haml
@@ -18,8 +18,8 @@ layout: project-standard
 .ui.grid.documentation-versions
   - project_description.release_series.values.each do |series|
     - release = series.releases[0]
-    - getting_started_guide = getting_started_guide(project_description, series)
-    - if not getting_started_guide.nil?
+    - getting_started_guides = getting_started_guides(project_description, series)
+    - if not getting_started_guides.empty?
       .ui.row
         .three.wide.column
           %span.ui.label.series= series.version
@@ -29,16 +29,19 @@ layout: project-standard
               %strong= release.version
               %span.detail= release.date
             = partial( 'project/series-status-label.html.haml', { "series" => series, "classes" => "tag" } )
-            %p
-              %span.ui.label.basic.horizontal
-                Getting started guide
-              - if not getting_started_guide.html_url.nil?
-                %a.ui.right.labeled.icon.button.small(href="#{getting_started_guide.html_url}")
-                  %i.icon.file.text.outline
-                  HTML
-              - if not getting_started_guide.pdf_url.nil?
-                %a.ui.right.labeled.icon.button.small(href="#{getting_started_guide.pdf_url}")
-                  %i.icon.file.pdf.outline
-                  PDF
+            - getting_started_guides.each do |getting_started_guide|
+              %p
+                %span.ui.label.basic.horizontal
+                  Getting started guide
+                  - if getting_started_guide.name
+                    = "(#{getting_started_guide.name})"
+                - if not getting_started_guide.html_url.nil?
+                  %a.ui.right.labeled.icon.button.small(href="#{getting_started_guide.html_url}")
+                    %i.icon.file.text.outline
+                    HTML
+                - if not getting_started_guide.pdf_url.nil?
+                  %a.ui.right.labeled.icon.button.small(href="#{getting_started_guide.pdf_url}")
+                    %i.icon.file.pdf.outline
+                    PDF
 
 ~ content
diff --git a/_layouts/project/project-releases-series.html.haml b/_layouts/project/project-releases-series.html.haml
@@ -14,7 +14,7 @@ project_hero_partial: project/hero-series.html.haml
 
 - latest_release_maven = maven(project_description, series, latest_release)
 
-- getting_started_guide = getting_started_guide(project_description, series)
+- getting_started_guides = getting_started_guides(project_description, series)
 - migration_guide = migration_guide(project_description, series)
 - dist_sourceforge = dist_sourceforge(project_description, series, latest_release)
 
@@ -33,7 +33,7 @@ project_hero_partial: project/hero-series.html.haml
     %li
       %a.item{:href => "#get-it"}
         How to get it
-    - if not getting_started_guide.nil?
+    - if not getting_started_guides.empty?
       %li
         %a.item{:href => "#getting_started"}
           Getting started
@@ -237,7 +237,7 @@ project_hero_partial: project/hero-series.html.haml
   %a{:href => "#releases"}
     here.
 
-- if not getting_started_guide.nil?
+- if not getting_started_guides.empty?
   %h2{:id => "getting_started"} Getting started
   - if series.status == 'end-of-life'
     :asciidoc
@@ -261,15 +261,19 @@ project_hero_partial: project/hero-series.html.haml
       ====
   %p
     If you want to start using #{project_description.name} #{series.version}, please refer to the getting started guide:
-  %p
-    - if not getting_started_guide.html_url.nil?
-      %a.ui.right.labeled.icon.button.small(href="#{getting_started_guide.html_url}")
-        %i.icon.file.text.outline
-        HTML
-    - if not getting_started_guide.pdf_url.nil?
-      %a.ui.right.labeled.icon.button.small(href="#{getting_started_guide.pdf_url}")
-        %i.icon.file.pdf.outline
-        PDF
+  - getting_started_guides.each do |getting_started_guide|
+    %p
+      - if getting_started_guide.name
+        %span.ui.label.basic.horizontal
+          = getting_started_guide.name
+      - if not getting_started_guide.html_url.nil?
+        %a.ui.right.labeled.icon.button.small(href="#{getting_started_guide.html_url}")
+          %i.icon.file.text.outline
+          HTML
+      - if not getting_started_guide.pdf_url.nil?
+        %a.ui.right.labeled.icon.button.small(href="#{getting_started_guide.pdf_url}")
+          %i.icon.file.pdf.outline
+          PDF
 
 - if not migration_guide.nil?
   %h2{:id => "migrate"} Migrating
diff --git a/_partials/project/about-buttons.html.haml b/_partials/project/about-buttons.html.haml
@@ -3,13 +3,16 @@
 - stable_series = latest_stable_series(real_page)
 - series = latest_series(real_page)
 - dev_series = next_dev_series(real_page)
-- get_started_url = project_description.nil? || stable_series.nil? ? nil : getting_started_guide(project_description, stable_series)&.html_url
+- getting_started_guides = project_description.nil? || stable_series.nil? ? [] : getting_started_guides(project_description, stable_series)
 
-- if not get_started_url.nil?
-  .jumbotron-button
-    %a.ui.small.right.labeled.icon.button{:href => "#{get_started_url}"}
-      %i.right.arrow.icon
-      Getting started
+- if not getting_started_guides.empty?
+  - getting_started_guides.each do |getting_started_guide|
+    .jumbotron-button
+      %a.ui.small.right.labeled.icon.button{:href => "#{getting_started_guide&.html_url}"}
+        %i.right.arrow.icon
+        Getting started
+        - if getting_started_guide.name
+          = "(#{getting_started_guide.name})"
 - if not (stable_series.nil? && dev_series.nil?)
   - unless stable_series.nil?
     .jumbotron-button
diff --git a/_partials/project/documentation-buttons.html.haml b/_partials/project/documentation-buttons.html.haml
@@ -2,13 +2,16 @@
 - project_description = site.projects[real_page.project]
 - stable_series = latest_stable_series(real_page)
 - series = latest_series(real_page)
-- get_started_url = stable_series.nil? ? nil : getting_started_guide(project_description, stable_series)&.html_url
+- getting_started_guides = stable_series.nil? ? [] : getting_started_guides(project_description, stable_series)
 
-- if not get_started_url.nil?
-  .jumbotron-button
-    %a.ui.small.right.labeled.icon.button{:href => "#{get_started_url}"}
-      %i.right.arrow.icon
-      Getting started
+- if not getting_started_guides.empty?
+  - getting_started_guides.each do |getting_started_guide|
+    .jumbotron-button
+      %a.ui.small.right.labeled.icon.button{:href => "#{getting_started_guide&.html_url}"}
+        %i.right.arrow.icon
+        Getting started
+        - if getting_started_guide.name
+          = "(#{getting_started_guide.name})"
 - unless stable_series.nil?
   .jumbotron-button
     - reference_doc = reference_doc(project_description, series)
diff --git a/reactive/index.html.haml b/reactive/index.html.haml
@@ -7,12 +7,12 @@ project: reactive
 - project = site.projects[page.project] 
 -# Latest series available unless a stable release exists
 - series = project.latest_stable_series.nil? ? project.latest_series : project.latest_stable_series
-- getting_started_guide = getting_started_guide(project, series)
+- getting_started_guides = getting_started_guides(project, series)
 
 -# Center body
 .feature-block
   :asciidoc
-    :getting_started_guide_link: #{getting_started_guide.html_url}
+    :getting_started_guide_link: #{getting_started_guides.first.html_url}
     :introduction: http://hibernate.org/reactive/documentation/1.0/reference/html_single/
     :build: http://hibernate.org/reactive/documentation/1.0/reference/html_single/#_including_hibernate_reactive_in_your_project_build
     :config: http://hibernate.org/reactive/documentation/1.0/reference/html_single/#_basic_configuration
