OPSEXP-2620 Generate documentation website with jekyll (#288)

.github/workflows/docs.yml

@@ -0,0 +1,29 @@
+name: Publish docs
+
+permissions:
+  contents: write
+  pages: write
+  id-token: write
+
+on:
+  pull_request:
+    branches:
+      - main
+    paths:
+      - 'docs/**'
+      - .github/workflows/docs.yml
+      - _config.yml
+      - Gemfile*
+      - charts/**/README.md
+  workflow_run:
+    workflows: [Release Charts]
+    types: [completed]
+
+jobs:
+  publish:
+    uses: Alfresco/jekyll-build-tools/.github/workflows/jekyll-publish.yml@4a682d36e45971f30e235c28f7b8a0898574b1b7
+    if: github.event_name == 'pull_request' || github.event.workflow_run.conclusion == 'success'
+    with:
+      working-directory: .
+      publish: ${{ github.event_name == 'workflow_run' && github.event.workflow_run.head_branch == 'main' }}
+      publish-branch: gh-pages

.github/workflows/lint-test.yaml

@@ -9,6 +9,11 @@ on:
       - reopened
       - synchronize
       - labeled
+    paths:
+      - 'charts/**'
+      - '!charts/**/README.md'
+      - '!charts/**/README.md.gotmpl'
+      - '!charts/**/docs/**'
 
 jobs:
   lint-test:

.gitignore

@@ -7,3 +7,5 @@
 merged.yaml
 alfresco-updatecli
 charts/*/render
+
+_site

.ruby-version

@@ -0,0 +1 @@
+3.1.4

Gemfile

@@ -0,0 +1,6 @@
+source 'https://rubygems.org'
+
+gem "jekyll", "~> 4.3.3"
+gem "just-the-docs", "0.8.1"
+gem "jekyll-relative-links"
+gem "html-proofer"

Gemfile.lock

@@ -0,0 +1,148 @@
+GEM
+  remote: https://rubygems.org/
+  specs:
+    Ascii85 (1.1.0)
+    addressable (2.8.6)
+      public_suffix (>= 2.0.2, < 6.0)
+    afm (0.2.2)
+    async (2.11.0)
+      console (~> 1.25, >= 1.25.2)
+      fiber-annotation
+      io-event (~> 1.5, >= 1.5.1)
+      timers (~> 4.1)
+    bigdecimal (3.1.8)
+    colorator (1.1.0)
+    concurrent-ruby (1.2.3)
+    console (1.25.2)
+      fiber-annotation
+      fiber-local (~> 1.1)
+      json
+    em-websocket (0.5.3)
+      eventmachine (>= 0.12.9)
+      http_parser.rb (~> 0)
+    ethon (0.16.0)
+      ffi (>= 1.15.0)
+    eventmachine (1.2.7)
+    ffi (1.16.3)
+    fiber-annotation (0.2.0)
+    fiber-local (1.1.0)
+      fiber-storage
+    fiber-storage (0.1.0)
+    forwardable-extended (2.6.0)
+    google-protobuf (4.26.1-arm64-darwin)
+      rake (>= 13)
+    google-protobuf (4.26.1-x86_64-darwin)
+      rake (>= 13)
+    google-protobuf (4.26.1-x86_64-linux)
+      rake (>= 13)
+    hashery (2.1.2)
+    html-proofer (5.0.9)
+      addressable (~> 2.3)
+      async (~> 2.1)
+      nokogiri (~> 1.13)
+      pdf-reader (~> 2.11)
+      rainbow (~> 3.0)
+      typhoeus (~> 1.3)
+      yell (~> 2.0)
+      zeitwerk (~> 2.5)
+    http_parser.rb (0.8.0)
+    i18n (1.14.5)
+      concurrent-ruby (~> 1.0)
+    io-event (1.5.1)
+    jekyll (4.3.3)
+      addressable (~> 2.4)
+      colorator (~> 1.0)
+      em-websocket (~> 0.5)
+      i18n (~> 1.0)
+      jekyll-sass-converter (>= 2.0, < 4.0)
+      jekyll-watch (~> 2.0)
+      kramdown (~> 2.3, >= 2.3.1)
+      kramdown-parser-gfm (~> 1.0)
+      liquid (~> 4.0)
+      mercenary (>= 0.3.6, < 0.5)
+      pathutil (~> 0.9)
+      rouge (>= 3.0, < 5.0)
+      safe_yaml (~> 1.0)
+      terminal-table (>= 1.8, < 4.0)
+      webrick (~> 1.7)
+    jekyll-include-cache (0.2.1)
+      jekyll (>= 3.7, < 5.0)
+    jekyll-relative-links (0.7.0)
+      jekyll (>= 3.3, < 5.0)
+    jekyll-sass-converter (3.0.0)
+      sass-embedded (~> 1.54)
+    jekyll-seo-tag (2.8.0)
+      jekyll (>= 3.8, < 5.0)
+    jekyll-watch (2.2.1)
+      listen (~> 3.0)
+    json (2.7.2)
+    just-the-docs (0.8.1)
+      jekyll (>= 3.8.5)
+      jekyll-include-cache
+      jekyll-seo-tag (>= 2.0)
+      rake (>= 12.3.1)
+    kramdown (2.4.0)
+      rexml
+    kramdown-parser-gfm (1.1.0)
+      kramdown (~> 2.0)
+    liquid (4.0.4)
+    listen (3.9.0)
+      rb-fsevent (~> 0.10, >= 0.10.3)
+      rb-inotify (~> 0.9, >= 0.9.10)
+    mercenary (0.4.0)
+    nokogiri (1.16.4-arm64-darwin)
+      racc (~> 1.4)
+    nokogiri (1.16.4-x86_64-darwin)
+      racc (~> 1.4)
+    nokogiri (1.16.4-x86_64-linux)
+      racc (~> 1.4)
+    pathutil (0.16.2)
+      forwardable-extended (~> 2.6)
+    pdf-reader (2.12.0)
+      Ascii85 (~> 1.0)
+      afm (~> 0.2.1)
+      hashery (~> 2.0)
+      ruby-rc4
+      ttfunk
+    public_suffix (5.0.5)
+    racc (1.7.3)
+    rainbow (3.1.1)
+    rake (13.2.1)
+    rb-fsevent (0.11.2)
+    rb-inotify (0.10.1)
+      ffi (~> 1.0)
+    rexml (3.2.6)
+    rouge (4.2.1)
+    ruby-rc4 (0.1.5)
+    safe_yaml (1.0.5)
+    sass-embedded (1.77.0-arm64-darwin)
+      google-protobuf (>= 3.25, < 5.0)
+    sass-embedded (1.77.0-x86_64-darwin)
+      google-protobuf (>= 3.25, < 5.0)
+    sass-embedded (1.77.0-x86_64-linux-gnu)
+      google-protobuf (>= 3.25, < 5.0)
+    terminal-table (3.0.2)
+      unicode-display_width (>= 1.1.1, < 3)
+    timers (4.3.5)
+    ttfunk (1.8.0)
+      bigdecimal (~> 3.1)
+    typhoeus (1.4.1)
+      ethon (>= 0.9.0)
+    unicode-display_width (2.5.0)
+    webrick (1.8.1)
+    yell (2.2.2)
+    zeitwerk (2.6.13)
+
+PLATFORMS
+  arm64-darwin-23
+  x86_64-darwin-23
+  x86_64-linux
+
+DEPENDENCIES
+  html-proofer
+  jekyll (~> 4.3.3)
+  jekyll-relative-links
+  just-the-docs (= 0.8.1)
+
+BUNDLED WITH
+   2.3.26

docs/README.md → README.md

@@ -1,38 +1,12 @@
 # alfresco-helm-charts
 
-This repository aims at delivering independent and lightweight
-[Helm](https://helm.sh) charts for Alfresco Content Services platform that can
-be used as building blocks by devops teams to build the Content Services
-platform that match the organization needs.
-
-⚠️ The existing [Alfresco Helm
-Charts](https://github.com/Alfresco/acs-deployment/tree/master/helm/alfresco-content-services)
-remains available and has been updated to leverage charts hosted in this
-repository.
-
-If you want to understand what are the principles to leverage in order to build
-on top of Alfresco components' chart please refer to the
-[getting-started-with-alfresco-charts](./getting-started-with-alfresco-charts.md)
-
-Each individual chart has its own documentation page that's available in the
-chart directory in [charts/](../charts). There are the values available for
-each of them.
-
-## Testing
-
-Each chart is tested against a default configuration on
-[KinD](https://kind.sigs.k8s.io/). You can check the currently tested K8s version
-by looking at the `KIND_NODE_IMAGE` value in the main [lint-test
-workflow](../.github/workflows/lint-test.yaml).
-
-We are ensuring backward compatibility with older K8s versions with
-[kubeconform](https://github.com/yannh/kubeconform). You can check the oldest
- K8s version tested by looking at `kubernetes-version` inside the
- `kubeconform-helm-min` hook in [pre-commit
- configuration](../.pre-commit-config.yaml).
+User docs available at: [https://alfresco.github.io/alfresco-helm-charts/](https://alfresco.github.io/alfresco-helm-charts/)
 
 ## Development
 
+Each individual chart is available in the chart directory in
+[charts/](./charts).
+
 This repository follows the
 [helm/charts-repo-actions-demo](https://github.com/helm/charts-repo-actions-demo)
 template, that support the testing and the release of helm charts with the help
@@ -78,6 +52,19 @@ There is an initial support for bumping charts dependencies with
 [GHA
 workflow](https://github.com/Alfresco/alfresco-helm-charts/actions/workflows/updatecli.yaml).
 
+## Testing
+
+Each chart is tested against a default configuration on
+[KinD](https://kind.sigs.k8s.io/). You can check the currently tested K8s version
+by looking at the `KIND_NODE_IMAGE` value in the main [lint-test
+workflow](../.github/workflows/lint-test.yaml).
+
+We are ensuring backward compatibility with older K8s versions with
+[kubeconform](https://github.com/yannh/kubeconform). You can check the oldest
+ K8s version tested by looking at `kubernetes-version` inside the
+ `kubeconform-helm-min` hook in [pre-commit
+ configuration](../.pre-commit-config.yaml).
+
 ## Release
 
 * Ensure alfresco-common [version](../charts/alfresco-common/Chart.yaml) is not a

_config.yml

@@ -0,0 +1,48 @@
+title: Alfresco Helm Charts Documentation
+description: User documentation for the Alfresco component Helm Charts
+theme: just-the-docs
+color_scheme: alfresco
+
+url: https://alfresco.github.io/alfresco-helm-charts
+
+aux_links:
+  Docs: https://docs.alfresco.com/
+  GitHub Repository: https://github.com/Alfresco/alfresco-helm-charts
+
+aux_links_new_tab: true
+
+gh_edit_link: true
+gh_edit_link_text: "Improve this page on GitHub"
+gh_edit_repository: https://github.com/Alfresco/alfresco-helm-charts
+gh_edit_branch: main
+gh_edit_source: .
+gh_edit_view_mode: edit
+
+logo: "docs/images/hyland-alfresco-logos.png"
+favicon_ico: "/docs/images/favicon.ico"
+
+defaults:
+  # apply the default layout to all markdown pages
+  - scope:
+      path: "*"
+    values:
+      layout: "default"
+      render_with_liquid: false
+
+exclude:
+  - Brewfile
+  - '*/ci/*'
+  - Gemfile
+  - Gemfile.lock
+  - '*.yaml'
+  - '*/Chart.lock'
+  - '*/README.md.gotmpl'
+  - '*.tgz'
+  - scripts
+  - '*/NOTES.txt'
+  - README.md
+  - CODE_OF_CONDUCT.md
+  - LICENSE
+
+plugins:
+  - jekyll-relative-links

_includes/head_custom.html

@@ -0,0 +1,3 @@
+<style>
+    @import url('https://fonts.googleapis.com/css2?family=Inter:[email protected]&display=swap')
+</style>

_sass/color_schemes/alfresco.scss

@@ -0,0 +1,13 @@
+$link-color: #3273dc;
+$body-font-family: "Inter", sans-serif;
+
+$font-size-5: 0.88rem;
+
+.main-content {
+    color: #212328;
+    font-weight: 300;
+}
+
+td {
+    word-wrap: anywhere;
+}

charts/activemq/README.md

@@ -1,3 +1,8 @@
+---
+title: activemq
+parent: Charts Reference
+---
+
 # activemq
 
 ![Version: 3.5.3](https://img.shields.io/badge/Version-3.5.3-informational?style=flat-square) ![AppVersion: 5.18.4](https://img.shields.io/badge/AppVersion-5.18.4-informational?style=flat-square)

charts/activemq/README.md.gotmpl

@@ -1,3 +1,8 @@
+---
+title: {{ template "chart.name" . }}
+parent: Charts Reference
+---
+
 {{ template "chart.header" . }}
 {{ template "chart.deprecationWarning" . }}
 

charts/alfresco-activiti-admin/README.md

@@ -1,3 +1,8 @@
+---
+title: alfresco-activiti-admin
+parent: Charts Reference
+---
+
 # alfresco-activiti-admin
 
 ![Version: 0.1.1](https://img.shields.io/badge/Version-0.1.1-informational?style=flat-square) ![AppVersion: 24.2.0](https://img.shields.io/badge/AppVersion-24.2.0-informational?style=flat-square)

charts/alfresco-activiti-admin/README.md.gotmpl

@@ -1,3 +1,8 @@
+---
+title: {{ template "chart.name" . }}
+parent: Charts Reference
+---
+
 {{ template "chart.header" . }}
 {{ template "chart.deprecationWarning" . }}
 

charts/alfresco-activiti/README.md

@@ -1,3 +1,8 @@
+---
+title: alfresco-activiti
+parent: Charts Reference
+---
+
 # alfresco-activiti
 
 ![Version: 0.1.1](https://img.shields.io/badge/Version-0.1.1-informational?style=flat-square) ![AppVersion: 24.2.0](https://img.shields.io/badge/AppVersion-24.2.0-informational?style=flat-square)

charts/alfresco-activiti/README.md.gotmpl

@@ -1,3 +1,8 @@
+---
+title: {{ template "chart.name" . }}
+parent: Charts Reference
+---
+
 {{ template "chart.header" . }}
 {{ template "chart.deprecationWarning" . }}