feat: support subcategories, reorganise Engineering Handbook (#408)

meltano · Apr 21, 2023 · bd08a58 · bd08a58
1 parent 04723ce
commit bd08a58
Show file tree

Hide file tree

Showing 9 changed files with 57 additions and 14 deletions.
diff --git a/Gemfile.lock b/Gemfile.lock
@@ -77,6 +77,8 @@ GEM
     mercenary (0.4.0)
     nokogiri (1.12.5-arm64-darwin)
       racc (~> 1.4)
+    nokogiri (1.12.5-x86_64-darwin)
+      racc (~> 1.4)
     parallel (1.22.1)
     pathutil (0.16.2)
       forwardable-extended (~> 2.6)
@@ -105,6 +107,7 @@ PLATFORMS
   arm64-darwin-20
   arm64-darwin-21
   arm64-darwin-22
+  x86_64-darwin-22
 
 DEPENDENCIES
   html-proofer (~> 3.19)

diff --git a/_layouts/page.html b/_layouts/page.html
@@ -1,4 +1,3 @@
-<!-- TODO: The menu doesn't allow for subdirectories yet. See: https://bulma.io/documentation/components/menu/ -->
 <!DOCTYPE html>
 <html>
 
@@ -21,19 +20,54 @@
                     {% else %}
                       <span class="icon"><i class="fas fa-book-open"></i></span>
                     {% endif %}
-
                     {{ collection.name | capitalize }}
                     </p>
                     <ul class="menu-list">
+
+                      <!-- render pages without 'subcategory' front matter -->
                       {% assign items = site[collection.label] | sort: "weight" %}
                       {% for item in items %}
-                        <li>
-                          <a href="{{ item.url }}" class="{% if item.url == page.url %}is-active{% endif %}">
-                           {{ item.title }}
-                          </a>
-                        </li>
+                        {% unless item.subcategory %}
+                        <li><a href="{{ item.url }}" class="{% if item.url == page.url %}is-active{% endif %}">{{ item.title }}</a></li>
+                        {% endunless %}
                       {% endfor %}
-                      </ul>
+
+                      <!-- render pages with 'subcategory' front matter -->
+                      {% assign subcategories = site[collection.label] | map: "subcategory" | uniq | compact %}
+                      {% assign num_subcategories = subcategories | size %}
+                      {% if num_subcategories > 0 %}
+                        {% for subcategory in subcategories %}
+                          {% assign items = site[collection.label] | sort: "weight" | where: "subcategory", subcategory %}
+
+                          <!-- try to find an item in this subcategory called 'index' to use as header link -->
+                          {% assign index_url = "#" %}
+                          {% for item in items %}
+                            {% assign page_name = item.url | split:"/" | last %}
+                            {% if page_name == "index" %}
+                              {% assign index_url = item.url %}
+                            {% endif %}
+                          {% endfor %}
+
+                          <li>
+                            <a href="{{ index_url }}">
+                              <span class="icon"><i class="fa-regular fa-folder-open"></i></span>
+                              {{ subcategory }}
+                            </a>
+                            <ul>
+                            {% for item in items %}
+                              {% unless item.url == index_url %}
+                              <li>
+                                <a href="{{ item.url }}" class="{% if item.url == page.url %}is-active{% endif %}">{{ item.title }}</a>
+                              </li>
+                              {% endunless %}
+                            {% endfor %}
+                            </ul>
+                          </li>
+
+                        {% endfor %%}
+                      {% endif %}
+
+                    </ul>
                   {% endif %}
                 {% endfor %}
               {% endif %}

diff --git a/src/_engineering/dev-standards.md → src/_engineering/dev-standards/index.md b/src/_engineering/dev-standards.md → src/_engineering/dev-standards/index.md
@@ -1,7 +1,8 @@
 ---
 layout: page
 title: Dev Standards
-weight: 3
+weight: 1
+subcategory: Dev Standards
 ---
 
 This page is a resource for development standards across all Meltano products and Meltano code repos.

diff --git a/src/_engineering/merge-process.md → ...ngineering/dev-standards/merge-process.md b/src/_engineering/merge-process.md → ...ngineering/dev-standards/merge-process.md
@@ -2,6 +2,7 @@
 layout: page
 title: Pull Request (PR) Process
 weight: 2
+subcategory: Dev Standards
 ---
 
 ## Trivial Updates
@@ -11,7 +12,7 @@ A pull request that touches code is never trivial, but one that fixes a typo in
 
 Trivial updates, such as docs updates, do not require a logged issue.
 
-Outside of very trivial issues like typo's, if a PR is opened *without* an associated issue, the PR description should then briefly explain why the PR is needed or what led to its creation.
+Outside of very trivial issues like typo's, if a PR is opened _without_ an associated issue, the PR description should then briefly explain why the PR is needed or what led to its creation.
 
 ## PR Review Process
 
@@ -61,8 +62,7 @@ Occasionally we need to help a contributor get their PR completed by contributin
 
 #### Step 1: Author must allow edits from maintainers
 
-According to the [docs](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/working-with-forks/allowing-changes-to-a-pull-request-branch-created-from-a-fork
-):
+According to the [docs](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/working-with-forks/allowing-changes-to-a-pull-request-branch-created-from-a-fork):
 
 > Only pull request authors can give upstream repository maintainers, or those with push access to the upstream repository, permission to make commits to their pull request's compare branch in a user-owned fork.
 

diff --git a/src/_engineering/stable-increments.md → ...eering/dev-standards/stable-increments.md b/src/_engineering/stable-increments.md → ...eering/dev-standards/stable-increments.md
@@ -2,6 +2,7 @@
 layout: page
 title: Stable Increments
 weight: 3
+subcategory: Dev Standards
 ---
 
 This page describes stable vs unstable increments, and is primarily focused on Engineering use cases and applications.

diff --git a/src/_engineering/team-practices.md → src/_engineering/team-practices/index.md b/src/_engineering/team-practices.md → src/_engineering/team-practices/index.md
@@ -1,7 +1,8 @@
 ---
 layout: page
 title: Team Practices
-weight: 2
+weight: 1
+subcategory: Team Practices
 ---
 
 This page defines recurring practices which help the Engineering team to function effectively and efficiently.

diff --git a/src/_engineering/outages.md → src/_engineering/team-practices/outages.md b/src/_engineering/outages.md → src/_engineering/team-practices/outages.md
@@ -2,6 +2,7 @@
 layout: page
 title: Outages and Escalation
 weight: 3
+subcategory: Team Practices
 ---
 
 ## Types of escalations

diff --git a/src/_engineering/release-process.md → ...neering/team-practices/release-process.md b/src/_engineering/release-process.md → ...neering/team-practices/release-process.md
@@ -2,6 +2,7 @@
 layout: page
 title: Release Process
 weight: 2
+subcategory: Team Practices
 ---
 
 The process below applies to both Meltano and then SDK, unless otherwise noted.

diff --git a/src/_engineering/sensitive-data-handling.md → ...team-practices/sensitive-data-handling.md b/src/_engineering/sensitive-data-handling.md → ...team-practices/sensitive-data-handling.md
@@ -1,7 +1,8 @@
 ---
 layout: page
 title: Handling of Sensitive Data
-weight: 12
+weight: 3
+subcategory: Team Practices
 ---
 
 ## Data Classifications