Update the architecture page

[dscho]

After gitgitgadget/gitgitgadget#609 has been addressed, the architecture is noticeably different. Here is an attempt to visualize the new lay of the land:

[rimrul]

I don't love the positioning of the arrow labels overlapping multiple arrows, but there seems to be very little we can do about that.

[dscho]

I force-pushed some changes.

Range-diff

• 9: bc6fc86 ! 1: 9fc0bb6 Upgrade Hugo

  @@ Metadata
    ## Commit message ##
       Upgrade Hugo
   
  +    It is a good idea to stay up to date, anyway, but in this instance the
  +    motivation is to get across the breaking changes in
  +    https://github.com/gohugoio/hugo/releases/tag/v0.148.0 that affect how
  +    layouts work (something that I am about to use when I introduce support
  +    for Graphviz diagrams).
  +
       Signed-off-by: Johannes Schindelin <johannes.schindelin@gmx.de>
   
    ## hugo.yml ##

• 1: 8e1e093 = 2: c5403ef architecture: fix the link to GitGitGadget's Azure Function definition

• 2: 1aaef27 = 3: 33df62b architecture: adjust after the migration to GitHub Actions

• 3: 7a94922 = 4: 458dcd4 architecture: stop describing Azure Pipelines' individual tasks

• 4: a471c8e = 5: 51264ff architecture: adjust the Git GUI section

• 5: 69b8750 = 6: 2182f7d Add support for rendering Graphviz diagrams

• 6: af226bb ! 7: 5370634 architecture: preface it with some diagrams

  @@ content/architecture.md
   +
   +  GitGitGadget [label="GitGitGadget", fillcolor="#ffffff"];
   +
  -+  user -> pr_repo [taillabel=" opens PR"];
  ++  user -> pr_repo [label=" opens PR"];
   +
   +  pr_repo -> GitGitGadget [label="slash commands"];
   +
  @@ content/architecture.md
   +```graphviz
   +digraph GitGitGadgetFlow {
   +  layout="neato";
  -+  rankdir=TB;
  ++  rankdir="TB";
   +  splines=true;
   +  overlap=false;
  -+  fontname="Arial";
   +  fontsize=10;
   +  sep="+4.5";
   +
  -+  node [shape=box, style=filled];
  -+  edge [fontsize=7];
  ++  node [fontname="Arial", shape=box, style=filled];
  ++  edge [fontname="Arial", fontsize=7];
   +
   +  // Node styles
   +  user [label="user (Git contributor)", fillcolor="#7777ff"];

• 7: 266bccc = 8: f84301a Optionally pre-render the Graphviz diagrams

• 8: a2170ee = 9: a2aad48 deploy/pr: pre-render the Graphviz diagrams

• 10: a36b6ca < -: ------- Update content/architecture.md

[dscho]

Updates can be adored here: https://dscho.github.io/gitgitgadget.github.io/architecture

[rimrul]

I did some fiddling with overlapping edges, unlabled edges, label placement and readability. What do you think of

digraph GitGitGadgetFlow {
  layout="neato";
  rankdir="TB";
  splines=true;
  overlap=false;
  fontsize=10;
  sep="+4.5";
  node [fontname="Arial", shape=box, style=filled];
  edge [fontname="Arial", fontsize=7];
  // Node styles
  user [label="user (Git contributor)", fillcolor="#7777ff"];
  pr_repo [label="pr-repo", fillcolor="#eaa666", penwidth=2];
  upstream_repo [label="upstream-repo", fillcolor="#eaa666", penwidth=2];
  test_repo [label="test-repo", fillcolor="#eaa666", penwidth=2];
  GitGitGadget [label="GitGitGadget", fillcolor="#ffffff"];
  gitgitgadget_github_app_repo [label="gitgitgadget-github-app-repo", fillcolor="#fb7", penwidth=2];
  azure_function [label="azure-function", fillcolor="#ffffff"];
  gitgitgadget_workflows_repo [label="gitgitgadget-workflows-repo", fillcolor="#fb7", penwidth=2];
  gitgitgadget_repo [label="gitgitgadget-repo", fillcolor="#fb7", penwidth=2];
  mailing_list [label="mailing-list", fillcolor="#ffffff"];
  mailing_list_repo [label="mailing-list-repo", fillcolor="#fb7", penwidth=2];
  mailing_list_repo_mirror [label="mailing-list-repo-mirror", fillcolor="#fb7", penwidth=2];
  user -> pr_repo:nw [taillabel="     opens PR"];
  user -> upstream_repo [taillabel="opens PR"];
  user -> test_repo [taillabel=" opens PR"];
  upstream_repo -> pr_repo:se [label="syncs\nbranches"];
  pr_repo -> GitGitGadget [headlabel="slash commands"];
  upstream_repo -> GitGitGadget [label="slash commands\n(App)"];
  test_repo -> GitGitGadget [label="slash commands  \n(owner only)"];
  GitGitGadget -> mailing_list [label="sends patch series  "];
  GitGitGadget -> gitgitgadget_workflows_repo [label="runs in"];
  gitgitgadget_workflows_repo -> gitgitgadget_repo [label="uses Actions  "];
  pr_repo -> azure_function [label="webhook  "];
  upstream_repo -> azure_function [label="webhook  "];
  test_repo -> azure_function [label="webhook"];
  mailing_list_repo_mirror:ne -> azure_function:w [taillabel="       webhook"];
  gitgitgadget_github_app_repo -> azure_function [label="deploys to  "];
  azure_function -> GitGitGadget [headlabel="triggers            "];
  mailing_list:sw -> mailing_list_repo:se [label="public-inbox"];
  mailing_list_repo -> mailing_list_repo_mirror [label="syncs to  "];
  mailing_list_repo_mirror:se -> pr_repo [label="mirrors\nreplies"];
  mailing_list_repo_mirror -> upstream_repo  [label="mirrors replies       "];
  mailing_list_repo_mirror:n -> test_repo  [label="mirrors replies"];
}

[dscho]

What do you think

I love it! And I integrated your changes as b81468e. See it in action here: https://dscho.github.io/gitgitgadget.github.io/architecture

[dscho]

Range-diff

• 1: 2182f7d ! 1: 17ef958 Add support for rendering Graphviz diagrams

  @@ layouts/_default/baseof.html
   +{{- if .Store.Get "hasGraphviz" }}
   +  <script src="{{ relURL "js/viz-global.js" }}"> </script>
   +  <script type="text/javascript">
  ++    let vizInstance
   +    window.addEventListener("DOMContentLoaded", async () => {
  -+      for (const x of [...document.querySelectorAll("pre[class=graphviz]")]) {
  ++      [...document.querySelectorAll("pre[class=graphviz]")].forEach(async (x) => {
  ++        if (!vizInstance) vizInstance = await Viz.instance()
   +        if (x.style.display === 'none') return
  -+        const engine = x.getAttribute('engine') || 'dot'
   +        const svg = (await Viz.instance()).renderSVGElement(x.innerText, { engine })
   +        x.parentNode.insertBefore(svg, x)
   +        x.style.display = 'none'
  -+      }
  ++      })
   +    })
   +  </script>
   +{{- end }}

• -: ------- > 2: 3e9e79d graphviz: use <img> elements instead of ones

• -: ------- > 3: 6e89300 graphviz: make the diagrams' background transparent by default

• -: ------- > 4: 37e69c9 graphviz: allow overriding the engine

• 3: f84301a ! 5: 9a5e2a2 Optionally pre-render the Graphviz diagrams

  @@ Commit message
    ## content/diagram-list.html (new) ##
   @@
   +---
  -+layout: diagram-list
  ++outputs:
  ++  - json
   +---
   
  - ## layouts/diagram-list.html (new) ##
  + ## hugo.yml ##
  +@@ hugo.yml: markup:
  +   goldmark:
  +     renderer:
  +       unsafe: true
  ++mediaTypes:
  ++  application/json:
  ++    suffixes:
  ++    - json
  + module:
  +   mounts:
  +   - source: content
  +
  + ## layouts/_default/single.json.json (new) ##
   @@
  -+<pre>
  -+{{- range .Site.RegularPages -}}
  -+  {{- if in .RawContent "```graphviz" -}}
  -+    public{{ .Path }}.html
  -+  {{- end }}
  -+{{ end -}}
  -+</pre>
  ++{{- $diagram_list := where .Site.Pages "RawContent" "like" "```graphviz" -}}
  ++{{- $diagram_list | jsonify -}}
   
    ## package-lock.json (new) ##
   @@
  @@ script/graphviz-ssr.js (new)
   + * via `viz-js`.
   + */
   +;(async () => {
  -+  const opts = { format: "svg" }
  -+  for (const path of readFileSync("public/diagram-list.html", "utf-8")
  -+    .split("\n")
  -+    .filter((x) => x.startsWith("public/"))) {
  ++  for (const { Path: pathInPublic } of JSON.parse(readFileSync("public/diagram-list.json", "utf-8"))) {
  ++    const path = `public${pathInPublic}.html`
   +    const contents = readFileSync(path, "utf-8")
   +    const html = parse(contents)
   +    const vizImport = html.querySelector('script[src$="viz-global.js"]')
  @@ script/graphviz-ssr.js (new)
   +    vizImport.remove() // remove the import
   +
   +    for (const pre of html.querySelectorAll("pre.graphviz")) {
  -+      const svg = (await Viz.instance()).renderString(pre.textContent, opts)
  -+      pre.replaceWith(svg.substring(svg.indexOf("<svg")))
  ++      const engine = pre.getAttribute("engine") || "dot"
  ++      const svg = (await Viz.instance()).renderString(pre.textContent, {
  ++        format: "svg",
  ++        graphAttributes: {
  ++          bgcolor: "transparent",
  ++        },
  ++        engine,
  ++      })
  ++      const dataURL = `data:image/svg+xml;base64,${Buffer.from(svg).toString("base64")}`
  ++      pre.replaceWith(`<img src="${dataURL}" />`)
   +    }
   +    console.log(`Rewriting ${path}`)
   +    writeFileSync(`${path}`, html.toString())

• -: ------- > 6: 12ac91b graphviz: support the alt attribute

• 4: a2aad48 = 7: 5ceac84 deploy/pr: pre-render the Graphviz diagrams

• 2: 5370634 ! 8: 3a064ae architecture: preface it with some diagrams

  @@ content/architecture.md
   +  fontsize=10;
   +  sep="+4.5";
   +
  -+  node [fontname="Arial", shape=box, style=filled];
  ++  node [fontname="Arial", shape=box, style="filled,rounded"];
   +  edge [fontname="Arial", fontsize=7];
   +
   +  // Node styles
  @@ content/architecture.md
   +  fontsize=10;
   +  sep="+4.5";
   +
  -+  node [fontname="Arial", shape=box, style=filled];
  ++  node [fontname="Arial", shape=box, style="filled,rounded"];
   +  edge [fontname="Arial", fontsize=7];
   +
   +  // Node styles

• 5: b81468e = 9: 24de833 architecture: improve the diagram layout

[dscho]

@rimrul as before, I pushed to my fork so that it can be seen in action: https://dscho.github.io/gitgitgadget.github.io/architecture

[rimrul]

LGTM