README templating prerequisites

template/.github/workflows/build.yml.j2

@@ -245,6 +245,31 @@ jobs:
  with:
  command: test
 
+ # Similar to check_charts, this tries to render the README, and see if there are unintended changes.
+ # This will save us from merging changes to the wrong file (instead of the templated source), and from
+ # forgetting to render out modifications to the README.
+ check_readme:
+ name: Check if committed README is the one we would render from the available parts
+ runs-on: ubuntu-latest
+ steps:
+ - name: Checkout
+ uses: actions/checkout@2541b1294d2704b0964813337f33b291d3f8596b # tag=v3.0.2
+ with:
+ submodules: recursive
+ - uses: actions/setup-python@v4
+ with:
+ python-version: '3.10'
+ - name: Regenerate charts
+ run: make render-readme
+ - name: Check if committed README were up to date
+ run: git diff --exit-code
+ - name: Git Diff showed uncommitted changes
+ if: ${{ failure() }}
+ uses: actions/github-script@d50f485531ba88479582bc2da03ff424389af5c1 # tag=v6
+ with:
+ script: |
+ core.setFailed('Committed README are not up to date, please make sure to apply them to the templated partials, and re-commit!')
+
  # This job cleans up the CRDs, Helm charts and Kustomize manifests, followed by rebuilding them
  # It then runs a `git diff` and fails the entire workflow, if any difference is encountered.
  #

template/.readme/partials/borrowed/documentation.md.j2.j2

@@ -0,0 +1,5 @@
+## Documentation
+
+The documentation for this operator can be found [here](https://docs.stackable.tech/{{operator_name}}/stable/index.html).
+
+The documentation for all Stackable products can be found at [docs.stackable.tech](https://docs.stackable.tech).

template/.readme/partials/borrowed/footer.md.j2.j2

@@ -0,0 +1,56 @@
+## About The Stackable Data Platform
+
+This operator is written and maintained by [Stackable](https://www.stackable.tech) and it is part of a larger platform.
+
+![Stackable Data Platform Overview](./.readme/static/borrowed/sdp_overview.png)
+
+Stackable makes it easy to operate data applications in any Kubernetes cluster.
+
+The data platform offers many operators, new ones being added continuously. All our operators are designed and built to be easily interconnected and to be consistent to work with.
+
+Stackable GmbH is the company behind the Stackable Data Platform. Offering professional services, paid support plans and development.
+
+We love open-source!
+
+## Supported Platforms
+
+We develop and test our operators for the following cloud platforms:
+
+* Kubernetes 1.21-1.24
+* EKS on Amazon Web Services (AWS)
+* GKE on Google Cloud Platform (GCP)
+* AKS on Microsoft Azure
+* K3s
+
+We are currently working to support:
+
+* OpenShift
+
+## Other Operators
+
+These are the Operators currently part of the Stackable Data Platform:
+
+- [Apache Airflow Operator](https://github.com/stackabletech/airflow-operator)
+- [Apache Druid Operator](https://github.com/stackabletech/druid-operator)
+- [Apache HBase Operator](https://github.com/stackabletech/hbase-operator)
+- [Apache Hadoop HDFS Operator](https://github.com/stackabletech/hdfs-operator)
+- [Apache Hive Operator](https://github.com/stackabletech/hive-operator)
+- [Apache Kafka Operator](https://github.com/stackabletech/kafka-operator)
+- [Apache NiFi Operator](https://github.com/stackabletech/nifi-operator)
+- [Apache Spark Operator](https://github.com/stackabletech/spark-k8s-operator)
+- [Apache Superset Operator](https://github.com/stackabletech/superset-operator)
+- [Trino Operator](https://github.com/stackabletech/trino-operator)
+- [Apache ZooKeeper Operator](https://github.com/stackabletech/zookeeper-operator)
+- [OpenPolicyAgent Operator](https://github.com/stackabletech/opa-operator)
+
+## Contributing
+
+Contributions are welcome. Follow our [Contributors Guide](https://docs.stackable.tech/home/stable/contributor/index.html) to learn how you can contribute.
+
+## License
+
+[Open Software License version 3.0](./LICENSE).
+
+## Support
+
+You can use this project under different licenses. Get started with the community edition! If you want professional support, [we offer subscription plans](https://stackable.tech/en/plans/).

template/.readme/partials/borrowed/header.md.j2.j2

@@ -0,0 +1,5 @@
+<p align="center">
+ <img width="150" src="./.readme/static/borrowed/Icon_Stackable.svg" alt="Stackable Logo"/>
+</p>
+
+<h1 align="center">{{title}}</h1>

template/.readme/partials/borrowed/links.md.j2.j2

@@ -0,0 +1,6 @@
+[![Build Actions Status](https://ci.stackable.tech/job/{{operator_name}}%2doperator%2dit%2dnightly/badge/icon?subject=Integration%20Tests)](https://ci.stackable.tech/job/{{operator_name}}%2doperator%2dit%2dnightly)
+[![Maintenance](https://img.shields.io/badge/Maintained%3F-yes-green.svg)](https://GitHub.com/stackabletech/{{operator_name}}-operator/graphs/commit-activity)
+[![PRs Welcome](https://img.shields.io/badge/PRs-welcome-green.svg)](https://docs.stackable.tech/home/stable/contributor/index.html)
+[![License OSL3.0](https://img.shields.io/badge/license-OSL3.0-green)](./LICENSE)
+
+[Documentation](https://docs.stackable.tech/{{operator_name}}-operator/stable/index.html) {% if quickstart_link %}| [Quickstart]({{quickstart_link}}) {% endif %}| [Stackable Data Platform](https://stackable.tech/) | [Platform Docs](https://docs.stackable.tech/)

template/.readme/partials/borrowed/related_reading.md.j2.j2

@@ -0,0 +1,6 @@
+{%- if related_reading_links -%}
+## Related Reading
+{% for (text, link) in related_reading_links %}
+* [{{text}}]({{link}})
+{%- endfor %}
+{%- endif -%}

template/Makefile.j2

@@ -20,6 +20,9 @@ export VERSION IS_NIGHTLY DOCS_VERSION
 
 SHELL=/usr/bin/env bash -euo pipefail
 
+render-readme:
+scripts/render_readme.sh
+
 ## Docker related targets
 docker-build:
 docker build --force-rm --build-arg VERSION=${VERSION} -t "docker.stackable.tech/stackable/{[ operator.name }]:${VERSION}" -f docker/Dockerfile .

template/scripts/ensure_one_trailing_newline.py

@@ -0,0 +1,89 @@
+"""
+Given the location of a file, trims all trailing blank lines and
+places a single one. Used as post-processing step for README rendering.
+"""
+import re
+import unittest
+
+BLANK_LINE_REGEX_PATTERN = r"^\s*$"
+
+
+def has_trailing_newline(line):
+ return line[-1:] == "\n"
+
+
+def process_lines(lines):
+ trim_count = 0
+ # trim trailing blank lines
+ for line in lines[::-1]:
+ if re.match(BLANK_LINE_REGEX_PATTERN, line):
+ trim_count += 1
+ else:
+ break
+
+ cutoff_index = len(lines) - trim_count
+ new_lines = lines[:cutoff_index]
+
+ # maybe add a newline character to the last sensible line
+ if not has_trailing_newline(new_lines[-1]):
+ new_lines[-1] = new_lines[-1] + "\n"
+
+ # add a trailing blank line without newline
+ new_lines.append("")
+ return new_lines
+
+
+class TestCoreMethods(unittest.TestCase):
+
+ def test_trailing_new_line(self):
+ self.assertTrue(has_trailing_newline("something\n"))
+ self.assertTrue(has_trailing_newline("\n"))
+ self.assertFalse(has_trailing_newline("nope"))
+
+ def test_trailing_real_line(self):
+ lines = ["bla\n", "useful"]
+ processed_lines = process_lines(lines)
+ self.assertEqual(len(processed_lines), 3)
+ self.assertTrue(has_trailing_newline(processed_lines[0]))
+ self.assertTrue(has_trailing_newline(processed_lines[1]))
+ self.assertFalse(has_trailing_newline(processed_lines[2]))
+
+ def test_lots_of_empties(self):
+ lines = ["bla\n", "\n", "\n", "\n", "\n"]
+ processed_lines = process_lines(lines)
+ self.assertEqual(len(processed_lines), 2)
+ self.assertEqual(processed_lines[-1], "")
+
+ def test_one_trailing_new_line(self):
+ lines = ["bla\n", "\n"]
+ processed_lines = process_lines(lines)
+ self.assertEqual(len(processed_lines), 2)
+ self.assertEqual(processed_lines[-1], "")
+
+ def test_one_trailing_blank_line(self):
+ lines = ["bla\n", ""]
+ processed_lines = process_lines(lines)
+ self.assertEqual(len(processed_lines), 2)
+ self.assertEqual(processed_lines[-1], "")
+
+
+if __name__ == "__main__":
+ # to run tests for this script:
+ # python3 -m unittest ensure_one_trailing_newline.py
+
+ import sys
+
+ if len(sys.argv) != 2:
+ print("Usage: {} filename_to_trim".format(sys.argv[0]))
+ exit(1)
+
+ file_name = sys.argv[1]
+
+ lines = []
+ with open(file_name, "r") as f:
+ lines = f.readlines()
+
+ lines = process_lines(lines)
+
+ with open(file_name, "w") as f:
+ f.write("".join(lines))

template/scripts/render_readme.sh

@@ -0,0 +1,16 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# Check if jinja2 is there
+if ! command -v jinja2 &> /dev/null
+then
+ echo "jinja2 could not be found. Use 'pip install jinja2-cli' to install it."
+ exit
+fi
+
+SCRIPT_DIR=$(dirname "$0")
+cd "$SCRIPT_DIR/../.readme"
+jinja2 README.md.j2 -o ../README.md
+cd ..
+
+python3 scripts/ensure_one_trailing_newline.py README.md