Added GitHub buttons, terraform and github action icons, fixed broken example links (#558)

Added GitHub buttons, terraform and github action icons, fixed broken example links

Author: zdmytriv

package-lock.json

@@ -24,6 +24,7 @@
     "prism-react-renderer": "^1.3.5",
     "react": "^17.0.2",
     "react-dom": "^17.0.2",
+    "react-github-btn": "^1.4.0",
     "sass": "^1.57.1"
   },
   "devDependencies": {

package.json

@@ -20,6 +20,7 @@ def _pre_rendering_fixes(self, repo, module_download_dir):
         content = io.read_file_to_string(readme_yaml_file)
         content = rendering.remove_targets_md(content)
         content = rendering.rename_name(repo, content)
+        content = rendering.fix_links_to_examples(repo, content)
         io.save_string_to_file(readme_yaml_file, content)
 
     def _post_rendering_fixes(self, repo, readme_md_file):

scripts/docs-collator/AbstractRenderer.py

@@ -1,14 +1,18 @@
 import re
 
+TAG_REGEX = re.compile('(<)([0-9a-zA-Z._-]+)(>)', re.IGNORECASE)
+BR_REGEX = re.compile(re.escape('<br>'), re.IGNORECASE)
+SIDEBAR_LABEL_REGEX = re.compile('sidebar_label: .*', re.IGNORECASE)
+CUSTOM_EDIT_URL_REGEX = re.compile('custom_edit_url: .*', re.IGNORECASE)
+NAME_REGEX = re.compile('name: .*', re.IGNORECASE)
+
 
 def fix_self_non_closing_br_tags(content):
-    regex = re.compile(re.escape('<br>'), re.IGNORECASE)
-    return regex.sub('<br/>', content)
+    return BR_REGEX.sub('<br/>', content)
 
 
 def fix_custom_non_self_closing_tags_in_pre(content):
     lines = content.splitlines()
-    tag_regex = re.compile('(<)([0-9a-zA-Z._-]+)(>)', re.IGNORECASE)
     fixed_lines = []
 
     for line in lines:
@@ -20,7 +24,7 @@ def fix_custom_non_self_closing_tags_in_pre(content):
 
         for group in groups:
             before = group
-            after = tag_regex.sub(r"&lt;\2&gt;", group)
+            after = TAG_REGEX.sub(r"&lt;\2&gt;", group)
             line = line.replace(f'<pre>{before}</pre>', f'<pre>{after}</pre>')
 
         fixed_lines.append(line)
@@ -29,15 +33,13 @@ def fix_custom_non_self_closing_tags_in_pre(content):
 
 
 def fix_sidebar_label(content, repo):
-    regex = re.compile('sidebar_label: .*', re.IGNORECASE)
     provider, module_name = parse_terraform_repo_name(repo.name)
-    return regex.sub(f'sidebar_label: {module_name}', content)
+    return SIDEBAR_LABEL_REGEX.sub(f'sidebar_label: {module_name}', content)
 
 
 def fix_github_edit_url(content, repo):
-    regex = re.compile('custom_edit_url: .*', re.IGNORECASE)
     github_edit_url = f"custom_edit_url: https://github.com/{repo.full_name}/blob/{repo.default_branch}/README.yaml"
-    return regex.sub(github_edit_url, content)
+    return CUSTOM_EDIT_URL_REGEX.sub(github_edit_url, content)
 
 
 def remove_logo_from_the_bottom(content):
@@ -56,8 +58,12 @@ def remove_prefix(string, prefix):
 
 
 def rename_name(repo, content):
-    regex = re.compile('name: .*', re.IGNORECASE)
-    return regex.sub(f'name: {repo.name}', content)
+    return NAME_REGEX.sub(f'name: {repo.name}', content)
+
+
+def fix_links_to_examples(repo, content):
+    return re.sub(r"(\[examples/.*])\((examples/.*)\)",
+                  rf"\1(https://github.com/{repo.full_name}/tree/{repo.default_branch}/\2)", content)
 
 
 def parse_terraform_repo_name(name):

scripts/docs-collator/utils/rendering.py

@@ -14,4 +14,5 @@ DOWNLOAD_TMP_DIR="${DOWNLOAD_TMP_DIR:-tmp/github-actions}"
 
 python scripts/docs-collator/render_docs_for_github_actions.py \
 	--download-dir "${DOWNLOAD_TMP_DIR}" \
-	--output-dir "${RENDERED_DOCS_DIR}"
+	--output-dir "${RENDERED_DOCS_DIR}" \
+	--excludes 'github-action-ci-terraform'

scripts/render-docs-for-github-actions.sh

@@ -0,0 +1,47 @@
+import React from "react";
+import GitHubButton from 'react-github-btn'
+
+export default function GitHubButtons({custom_edit_url}) {
+  if (custom_edit_url == undefined) {
+    return (<div/>);
+  } else {
+    const url = new URL(custom_edit_url);
+    const parts = url.pathname.split('/');
+
+    let repoFullName = parts[1] + '/' + parts[2];
+
+    return (
+      <div className="github_buttons">
+        <ul>
+          <li>
+            <GitHubButton
+              href={'https://github.com/' + repoFullName}
+              aria-label="Open GitHub">GitHub</GitHubButton>
+          </li>
+
+          <li>
+            <GitHubButton
+              href={'https://github.com/' + repoFullName + '/issues'}
+              data-show-count="true"
+              aria-label={'Issue ' + repoFullName + ' on GitHub'}>Issues</GitHubButton>
+          </li>
+
+          <li>
+            <GitHubButton
+              href={'https://github.com/' + repoFullName + '/fork'}
+              data-icon="octicon-repo-forked"
+              data-show-count="true"
+              aria-label={'Fork ' + repoFullName + ' on GitHub'}>Forks</GitHubButton>
+          </li>
+
+          <li>
+            <GitHubButton
+              href={'https://github.com/' + repoFullName}
+              data-icon="octicon-star"
+              data-show-count="true"
+              aria-label={'Star ' + repoFullName + ' on GitHub'}>Stars</GitHubButton>
+          </li>
+        </ul>
+      </div>);
+    }
+}

src/components/github-buttons/github-buttons.js

@@ -262,3 +262,19 @@ svg.landingLogo path {
 .footer__copyright {
     margin-left: 0;
 }
+
+.github_buttons > ul {
+  list-style-type: none;
+  padding-left: 0px;
+  margin-top: 5px;
+  margin-bottom: 10px;
+}
+
+.github_buttons > ul > li {
+  display: inline-block;
+  margin-right: 10px;
+}
+
+.markdown h1:first-child {
+  --ifm-h1-font-size: 2.5rem;
+}

src/css/custom.css

@@ -0,0 +1,113 @@
+import React from 'react';
+import clsx from 'clsx';
+import Link from '@docusaurus/Link';
+import {
+  findFirstCategoryLink,
+  useDocById,
+} from '@docusaurus/theme-common/internal';
+import isInternalUrl from '@docusaurus/isInternalUrl';
+import {translate} from '@docusaurus/Translate';
+import styles from './styles.module.css';
+function CardContainer({href, children}) {
+  return (
+    <Link
+      href={href}
+      className={clsx('card padding--lg', styles.cardContainer)}>
+      {children}
+    </Link>
+  );
+}
+function CardLayout({href, icon, title, description}) {
+  return (
+    <CardContainer href={href}>
+      <h2 className={clsx('text--truncate', styles.cardTitle)} title={title}>
+        {icon} {title}
+      </h2>
+      {description && (
+        <p
+          className={clsx('text--truncate', styles.cardDescription)}
+          title={description}>
+          {description}
+        </p>
+      )}
+    </CardContainer>
+  );
+}
+function ImageCardLayout({href, icon, title, description}) {
+  return (
+    <CardContainer href={href}>
+      <h2 className={clsx('text--truncate', styles.cardTitle)} title={title}>
+        <img src={icon} style={{ maxWidth: 16, minWidth: 16 }}/> {title}
+      </h2>
+      {description && (
+        <p
+          className={clsx('text--truncate', styles.cardDescription)}
+          title={description}>
+          {description}
+        </p>
+      )}
+    </CardContainer>
+  );
+}
+function CardCategory({item}) {
+  const href = findFirstCategoryLink(item);
+  // Unexpected: categories that don't have a link have been filtered upfront
+  if (!href) {
+    return null;
+  }
+  return (
+    <ImageCardLayout
+      href={href}
+      icon="/images/folder.svg"
+      title={item.label}
+      description={translate(
+        {
+          message: '{count} items',
+          id: 'theme.docs.DocCard.categoryDescription',
+          description:
+            'The default description for a category card in the generated index about how many items this category includes',
+        },
+        {count: item.items.length},
+      )}
+    />
+  );
+}
+function CardLink({item}) {
+  const icon = isInternalUrl(item.href) ? '/images/terraform-color-16.svg' : '🔗';
+  const doc = useDocById(item.docId ?? undefined);
+  return (
+    <CardLayout
+      href={item.href}
+      icon={icon}
+      title={item.label}
+      description={doc?.description}
+    />
+  );
+}
+function ImageCardLink({item, image}) {
+  const doc = useDocById(item.docId ?? undefined);
+  return (
+    <ImageCardLayout
+      href={item.href}
+      icon={image}
+      title={item.label}
+      description={doc?.description}
+    />
+  );
+}
+export default function DocCard({item}) {
+  switch (item.type) {
+    case 'link':
+      if(item.href.startsWith('/components/catalog/') || item.href.startsWith('/modules/catalog/')) {
+        return <ImageCardLink item={item} image='/images/terraform.svg' />
+      } else if(item.href.startsWith('/github-actions/catalog/')) {
+        return <ImageCardLink item={item} image='/images/github-actions.svg' />
+      } else {
+        return <CardLink item={item} />;
+      }
+    case 'category':
+      return <CardCategory item={item} />;
+    default:
+      throw new Error(`unknown item type ${JSON.stringify(item)}`);
+  }
+}