feat: add support for README partials (#207)

setup.py

@@ -23,6 +23,7 @@
     "colorlog",
     "jinja2",
     "packaging",
+    "PyYAML",
     "requests",
     "protobuf",
 ]

synthtool/gcp/common.py

@@ -15,6 +15,7 @@
 import json
 import os
 import re
+import yaml
 from pathlib import Path
 
 from synthtool.languages import node
@@ -62,6 +63,7 @@ def render(self, template_name: str, **kwargs) -> Path:
     #
     def _load_generic_metadata(self, metadata):
         self._load_samples(metadata)
+        self._load_partials(metadata)
 
         metadata["repo"] = {}
         if os.path.exists("./.repo-metadata.json"):
@@ -111,6 +113,24 @@ def _read_quickstart(self, samples_dir):
 
         return quickstart
 
+    #
+    # hand-crafted artisinal markdown can be provided in a .readme-partials.yml.
+    # The following fields are currently supported:
+    #
+    # introduction: a more thorough introduction than metadata["description"].
+    #
+    def _load_partials(self, metadata):
+        cwd_path = Path(os.getcwd())
+        partials_file = None
+        for file in [".readme-partials.yml", ".readme-partials.yaml"]:
+            if os.path.exists(cwd_path / file):
+                partials_file = cwd_path / file
+                break
+        if not partials_file:
+            return
+        with open(partials_file) as f:
+            metadata["partials"] = yaml.load(f, Loader=yaml.SafeLoader)
+
 
 #
 # parser to convert fooBar.js to Foo Bar.

synthtool/gcp/templates/node_library/README.md

@@ -8,7 +8,11 @@
 [![npm version](https://img.shields.io/npm/v/{{ metadata['name'] }}.svg)](https://www.npmjs.org/package/{{ metadata['name'] }})
 [![codecov](https://img.shields.io/codecov/c/github/{{ metadata['repo']['repo'] }}/master.svg?style=flat)](https://codecov.io/gh/{{ metadata['repo']['repo'] }})
 
+{% if metadata['partials'] and metadata['partials']['introduction'] %}
+{{ metadata['partials']['introduction'] }}
+{% else %}
 {{ metadata['description'] }}
+{% endif %}
 {% if metadata['deprecated'] %}
 | :warning: Deprecated Module |
 | --- |

tests/fixtures/.readme-partials.yml

@@ -0,0 +1,6 @@
+introduction: |-
+    [Cloud Storage](https://cloud.google.com/storage/docs) allows world-wide 
+    storage and retrieval of any amount of data at any time. You can use Google
+    Cloud Storage for a range of scenarios including serving website content,
+    storing data for archival and disaster recovery, or distributing large data
+    objects to users via direct download.

tests/test_templates.py

@@ -104,3 +104,18 @@ def test_hide_billing():
         "README.md", metadata={"repo": {"requires_billing": False}}
     ).read_text()
     assert "Enable billing for your project" not in result
+
+
+def test_readme_partials():
+    cwd = os.getcwd()
+    os.chdir(FIXTURES)
+
+    common_templates = common.CommonTemplates()
+    metadata = {}
+    common_templates._load_partials(metadata)
+    # should have populated introduction from partial.
+    assert (
+        "objects to users via direct download" in metadata["partials"]["introduction"]
+    )
+
+    os.chdir(cwd)