build out a readme template system for easy overrides

tedivm · tedivm · commit fd8349c2003f · 2021-10-25T16:48:09.000-05:00
diff --git a/action.yml b/action.yml
@@ -10,11 +10,6 @@ inputs:
     description: 'The python package whose version is being tracked.'
     required: true
 
-  project_description:
-    description: "A description of the project- this can be a full markdown text."
-    required: true
-    default: ""
-
   readme_path:
     description: 'The path to the README file to update.'
     required: true
@@ -83,7 +78,6 @@ runs:
         TEMPLATE_DIRECTORY: ${{ inputs.template_directory }}
         PACKAGE: ${{ inputs.package }}
         PROJECT_NAME: ${{ inputs.package }}
-        PROJECT_DESCRIPTION: ${{ inputs.project_description }}
         PYTHON_VERSIONS: "3.6 3.7 3.8 3.9 3.10"
         MAX_VERSIONS: ${{ inputs.max_versions }}
         ORGANIZATION: ${{ inputs.organization }}
diff --git a/readme_builder.py b/readme_builder.py
@@ -1,27 +1,49 @@
-from jinja2 import Environment, FileSystemLoader, select_autoescape
+from jinja2 import Environment, FileSystemLoader, ChoiceLoader, select_autoescape
 import os
+from pathlib import Path
 
-SCRIPT_DIR=os.path.dirname(os.path.realpath(__file__))
+subtemplates = [
+  "description",
+  "documentation",
+  "quick_start",
+  "tags"
+]
+
+template_paths = []
 
+# Use explicit user setting *or* default repo directory for templates.
+# These get called first, allowing repos to override action templates.
 TEMPLATE_DIR = os.environ.get("TEMPLATE_DIRECTORY", False)
-if not TEMPLATE_DIR or len(TEMPLATE_DIR) < 1:
-  TEMPLATE_DIR = f"{SCRIPT_DIR}/templates/"
+if TEMPLATE_DIR and len(TEMPLATE_DIR) > 0:
+  template_paths.append(FileSystemLoader(TEMPLATE_DIR))
+else:
+  WORKSPACE_DIR = os.environ.get("GITHUB_WORKSPACE", False)
+  if WORKSPACE_DIR:
+    workspace_template_path = Path(WORKSPACE_DIR, 'templates')
+    if workspace_template_path.exists():
+      template_paths.append(str(FileSystemLoader(workspace_template_path)))
+
+# Add the action templates as the final templates to check.
+SCRIPT_DIR=os.path.dirname(os.path.realpath(__file__))
+template_paths.append(FileSystemLoader(f"{SCRIPT_DIR}/templates/"))
 
 env = Environment(
-    loader=FileSystemLoader(TEMPLATE_DIR),
+    loader=ChoiceLoader(template_paths),
     autoescape=select_autoescape()
 )
 
-template = env.get_template("README.md")
-
 variables = {
   "package": os.environ["PACKAGE"],
   "project_name": os.environ["PROJECT_NAME"],
-  "description": os.environ["PROJECT_DESCRIPTION"],
   "package_versions": os.environ["PACKAGE_VERSIONS"].split(),
   "python_versions": os.environ["PYTHON_VERSIONS"].split(),
   "organization": os.environ["ORGANIZATION"],
   "repository": os.environ["REPOSITORY"]
 }
 
-print(template.render(**variables))
+for template_var in subtemplates:
+  subtemplate = env.get_template(f"{template_var}.md")
+  variables[template_var] = subtemplate.render(**variables)
+
+readme_template = env.get_template("README.md")
+print(readme_template.render(**variables))
diff --git a/templates/README.md b/templates/README.md
@@ -3,35 +3,7 @@
 
 {{ description }}
 
-## Quick Start
-
-### Full
-
-To pull the latest slim version:
-
-```bash
-docker pull ghcr.io/{{ organization  }}/{{ short_repository }}:py{{ python_versions|last }}-LATEST
-```
-
-To include it in the dockerfile instead:
-
-```dockerfile
-FROM ghcr.io/{{ organization  }}/{{ short_repository }}:py{{ python_versions|last }}-LATEST
-```
-
-### Slim
-
-To pull the latest slim version:
-
-```bash
-docker pull ghcr.io/{{ organization  }}/{{ short_repository }}:py{{ python_versions|last }}-slim-LATEST
-```
-
-To include it in the dockerfile instead:
-
-```dockerfile
-FROM ghcr.io/{{ organization  }}/{{ short_repository }}:py{{ python_versions|last }}-slim-LATEST
-```
+{{ quick_start }}
 
 ## Python Versions
 
@@ -65,23 +37,6 @@ Every tag in this repository supports these architectures:
 * linux/arm64
 * linux/arm/v7
 
+{{ tags }}
 
-## Tags
-
-* Recommended Image: `ghcr.io/{{ organization  }}/{{ short_repository }}:py{{ python_versions|last }}-{{ package_versions|last }}`
-* Slim Image: `ghcr.io/{{ organization  }}/{{ short_repository }}:py{{ python_versions|last }}-slim-{{ package_versions|last }}`
-
-Tags are based on the package version, python version, and the upstream container the container is based on.
-
-| {{package}} Version | Python Version | Full Container | Slim Container | Alpine Container |
-|---------------------|----------------|----------------|----------------|------------------|
-{%- for package_version in ["latest"] + package_versions|reverse|list -%}
-{%- for python_version in python_versions|reverse %}
-| {{ package_version }} | {{ python_version }} | py{{ python_version }}-{{ package_version }} | py{{ python_version }}-slim-{{ package_version }} | py{{ python_version }}-alpine-{{ package_version }} |
-{%- endfor %}
-{%- endfor %}
-
-
-### Older Tags
-
-Older tags are left for historic purposes but do not receive updates. A full list of tags can be found on the package's [registry page](https://github.com/{{ repository }}/pkgs/container/{{ short_repository }}).
+{{ documentation }}
diff --git a/templates/description.md b/templates/description.md
diff --git a/templates/documentation.md b/templates/documentation.md
diff --git a/templates/quick_start.md b/templates/quick_start.md
@@ -0,0 +1,29 @@
+## Quick Start
+
+### Full
+
+To pull the latest slim version:
+
+```bash
+docker pull ghcr.io/{{ organization  }}/{{ short_repository }}:py{{ python_versions|last }}-LATEST
+```
+
+To include it in the dockerfile instead:
+
+```dockerfile
+FROM ghcr.io/{{ organization  }}/{{ short_repository }}:py{{ python_versions|last }}-LATEST
+```
+
+### Slim
+
+To pull the latest slim version:
+
+```bash
+docker pull ghcr.io/{{ organization  }}/{{ short_repository }}:py{{ python_versions|last }}-slim-LATEST
+```
+
+To include it in the dockerfile instead:
+
+```dockerfile
+FROM ghcr.io/{{ organization  }}/{{ short_repository }}:py{{ python_versions|last }}-slim-LATEST
+```
diff --git a/templates/tags.md b/templates/tags.md
@@ -0,0 +1,19 @@
+## Tags
+
+* Recommended Image: `ghcr.io/{{ organization  }}/{{ short_repository }}:py{{ python_versions|last }}-{{ package_versions|last }}`
+* Slim Image: `ghcr.io/{{ organization  }}/{{ short_repository }}:py{{ python_versions|last }}-slim-{{ package_versions|last }}`
+
+Tags are based on the package version, python version, and the upstream container the container is based on.
+
+| {{ package }} Version | Python Version | Full Container | Slim Container | Alpine Container |
+|-----------------------|----------------|----------------|----------------|------------------|
+{%- for package_version in ["latest"] + package_versions|reverse|list -%}
+{%- for python_version in python_versions|reverse %}
+| {{ package_version }} | {{ python_version }} | py{{ python_version }}-{{ package_version }} | py{{ python_version }}-slim-{{ package_version }} | py{{ python_version }}-alpine-{{ package_version }} |
+{%- endfor %}
+{%- endfor %}
+
+
+### Older Tags
+
+Older tags are left for historic purposes but do not receive updates. A full list of tags can be found on the package's [registry page](https://github.com/{{ repository }}/pkgs/container/{{ short_repository }}).
diff --git a/test.sh b/test.sh
@@ -7,6 +7,5 @@ export PACKAGE_VERSIONS="0.13.3 0.13.4 0.14.0 0.15.0"
 export PYTHON_VERSIONS="3.6 3.7 3.8 3.9 3.10"
 export ORGANIZATION="TestOrganization"
 export REPOSITORY="TestOrganization/TestRepository"
-export PROJECT_DESCRIPTION="This project is a project."
 
 ./scripts/update_readme.sh -
