Skip to content

Commit 194b257

Browse files
marcusburghardtmarcusburghardt
authored
Merge pull request #9 from sonupreetam/013-sync-summary-arch-diagram
feat: add spec, makefile and update the docs for sync summary arch diagram
2 parents 6efc345 + 9c8a484 commit 194b257

11 files changed

Lines changed: 845 additions & 10 deletions

File tree

‎CONTRIBUTING.md‎

Lines changed: 22 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -44,9 +44,12 @@ oriented quickly.
4444
| Edit the homepage | `layouts/home.html` + `content/_index.md` |
4545
| Site-wide Hugo settings | `config/_default/hugo.toml` |
4646
| Theme/feature parameters | `config/_default/params.toml` |
47-
| Sync project content | `go run ./cmd/sync-content --org complytime --config sync-config.yaml --write` |
47+
| Sync project content | `make sync` (or `go run ./cmd/sync-content --org complytime --config sync-config.yaml --write`) |
48+
| Sync single repo | `make sync-single REPO=complytime/<name>` |
49+
| Dry-run sync (no writes) | `make sync-dry` |
4850
| Configure file sync | `sync-config.yaml` |
49-
| Run sync tool tests | `go test -race ./cmd/sync-content/...` |
51+
| Run sync tool tests | `make test-race` (or `go test -race ./cmd/sync-content/...`) |
52+
| Run all Go checks (CI) | `make check` |
5053

5154
---
5255

@@ -76,7 +79,8 @@ cd website
7679
npm install
7780

7881
# 3. Sync project content from GitHub (generates project pages and cards)
79-
go run ./cmd/sync-content --org complytime --config sync-config.yaml --write
82+
make sync
83+
# Equivalent without make: go run ./cmd/sync-content --org complytime --config sync-config.yaml --write
8084

8185
# 4. Start the dev server (live reload)
8286
npm run dev
@@ -197,7 +201,7 @@ the sync tool from GitHub org repositories. You do not need to create them
197201
manually. To add a new project:
198202

199203
1. Create the repository in the `complytime` GitHub org
200-
2. Run the sync tool: `go run ./cmd/sync-content --org complytime --config sync-config.yaml --write`
204+
2. Run the sync tool: `make sync` (or `go run ./cmd/sync-content --org complytime --config sync-config.yaml --write`)
201205
3. The repo will automatically get a section index, overview page, and landing
202206
page card
203207

@@ -396,8 +400,7 @@ style: fix indentation in home template
396400
- [ ] Pages render correctly on the dev server
397401
- [ ] No broken links or missing images
398402
- [ ] Frontmatter includes all required fields (`title`, `description`, `weight`)
399-
- [ ] If Go code was changed: `go vet ./...` and `gofmt -l ./cmd/sync-content/` are clean
400-
- [ ] If Go code was changed: `go test -race ./cmd/sync-content/...` passes
403+
- [ ] If Go code was changed: `make check` passes (`go vet`, `gofmt`, and `go test -race`)
401404
- [ ] Commit messages follow conventional format
402405
- [ ] DCO sign-off is present
403406

@@ -437,6 +440,19 @@ npm run build
437440

438441
### Testing the Sync Tool
439442

443+
The Makefile provides handy targets for all common sync and Go operations
444+
(run `make help` to see all available targets):
445+
446+
```bash
447+
make sync-dry # dry-run — reads GitHub, writes nothing
448+
make sync # apply changes to disk
449+
make sync-single REPO=complytime/complyctl # single-repo dry-run
450+
make check # go vet + fmt-check + race tests (CI equivalent)
451+
make test-race # tests with race detector only
452+
```
453+
454+
The equivalent raw commands, if you prefer not to use make:
455+
440456
Dry-run (preview without writing):
441457

442458
```bash

‎Makefile‎

Lines changed: 153 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,153 @@
1+
# SPDX-License-Identifier: Apache-2.0
2+
3+
# ---------------------------------------------------------------------------
4+
# Makefile — ComplyTime website developer workflow
5+
#
6+
# Quick reference:
7+
# make help — list all targets
8+
# make sync-dry — dry-run content sync (reads GitHub, writes nothing)
9+
# make sync — apply content sync to disk
10+
# make dev — start Hugo dev server (after syncing content)
11+
# make check — vet + fmt-check + race tests
12+
# ---------------------------------------------------------------------------
13+
14+
# Overridable variables
15+
ORG ?= complytime
16+
CONFIG ?= sync-config.yaml
17+
LOCK ?= .content-lock.json
18+
OUTPUT ?= .
19+
WORKERS ?= 5
20+
TIMEOUT ?= 3m
21+
REPO ?=
22+
23+
SYNC_BIN := cmd/sync-content/sync-content
24+
SYNC_PKG := ./cmd/sync-content/...
25+
26+
# Common flags passed to every sync invocation
27+
SYNC_FLAGS := --org $(ORG) --config $(CONFIG) --output $(OUTPUT) --workers $(WORKERS) --timeout $(TIMEOUT)
28+
ifdef REPO
29+
SYNC_FLAGS += --repo $(REPO)
30+
endif
31+
32+
.DEFAULT_GOAL := help
33+
34+
# ---------------------------------------------------------------------------
35+
# Help
36+
# ---------------------------------------------------------------------------
37+
38+
.PHONY: help
39+
help: ## Show this help message
40+
@awk 'BEGIN {FS = ":.*##"; printf "\nUsage:\n make \033[36m<target>\033[0m\n\nTargets:\n"} \
41+
/^[a-zA-Z_-]+:.*?##/ { printf " \033[36m%-22s\033[0m %s\n", $$1, $$2 }' $(MAKEFILE_LIST)
42+
43+
# ---------------------------------------------------------------------------
44+
# Go — build, test, lint
45+
# ---------------------------------------------------------------------------
46+
47+
.PHONY: build
48+
build: ## Compile the sync-content binary
49+
go build -o $(SYNC_BIN) ./cmd/sync-content
50+
51+
.PHONY: test
52+
test: ## Run all Go unit tests
53+
go test $(SYNC_PKG)
54+
55+
.PHONY: test-race
56+
test-race: ## Run Go tests with the race detector
57+
go test -race $(SYNC_PKG)
58+
59+
.PHONY: vet
60+
vet: ## Run go vet
61+
go vet $(SYNC_PKG)
62+
63+
.PHONY: fmt
64+
fmt: ## Format Go source files with gofmt
65+
gofmt -w cmd/sync-content/
66+
67+
.PHONY: fmt-check
68+
fmt-check: ## Check Go formatting (non-destructive)
69+
@out=$$(gofmt -l cmd/sync-content/); \
70+
if [ -n "$$out" ]; then \
71+
echo "The following files need formatting:"; \
72+
echo "$$out"; \
73+
exit 1; \
74+
fi
75+
76+
.PHONY: check
77+
check: vet fmt-check test-race ## Run vet + fmt-check + race tests (CI equivalent)
78+
79+
# ---------------------------------------------------------------------------
80+
# Content sync — uses GITHUB_TOKEN from the environment
81+
# ---------------------------------------------------------------------------
82+
83+
.PHONY: sync-dry
84+
sync-dry: build ## Dry-run content sync — reads GitHub, writes nothing to disk
85+
./$(SYNC_BIN) $(SYNC_FLAGS)
86+
87+
.PHONY: sync
88+
sync: build ## Apply content sync to disk (--write)
89+
./$(SYNC_BIN) $(SYNC_FLAGS) --write
90+
91+
.PHONY: sync-locked
92+
sync-locked: build ## Apply content sync at approved SHAs from .content-lock.json
93+
./$(SYNC_BIN) $(SYNC_FLAGS) --lock $(LOCK) --write
94+
95+
.PHONY: sync-update-lock
96+
sync-update-lock: build ## Refresh .content-lock.json with current upstream SHAs (no content write)
97+
./$(SYNC_BIN) $(SYNC_FLAGS) --lock $(LOCK) --update-lock
98+
99+
.PHONY: sync-single-dry
100+
sync-single-dry: ## Dry-run sync for one repo (REPO=complytime/complyctl)
101+
@if [ -z "$(REPO)" ]; then echo "Usage: make sync-single-dry REPO=complytime/<name>"; exit 1; fi
102+
$(MAKE) sync-dry REPO=$(REPO)
103+
104+
.PHONY: sync-single
105+
sync-single: ## Apply sync for one repo (REPO=complytime/complyctl)
106+
@if [ -z "$(REPO)" ]; then echo "Usage: make sync-single REPO=complytime/<name>"; exit 1; fi
107+
$(MAKE) sync REPO=$(REPO)
108+
109+
# ---------------------------------------------------------------------------
110+
# Hugo / Node — site build and dev server
111+
# ---------------------------------------------------------------------------
112+
113+
.PHONY: node-install
114+
node-install: ## Install Node dependencies (npm install)
115+
npm install
116+
117+
.PHONY: dev
118+
dev: ## Start the Hugo dev server (runs: npm run dev)
119+
npm run dev
120+
121+
.PHONY: site-build
122+
site-build: ## Build the Hugo site (runs: hugo --minify --gc)
123+
npm run build
124+
125+
.PHONY: preview
126+
preview: sync site-build ## Full preview: sync content then build the site
127+
128+
# ---------------------------------------------------------------------------
129+
# Housekeeping
130+
# ---------------------------------------------------------------------------
131+
132+
.PHONY: clean
133+
clean: ## Remove the compiled sync-content binary
134+
rm -f $(SYNC_BIN)
135+
136+
.PHONY: clean-build
137+
clean-build: ## Remove Hugo output + resource cache, then rebuild (CI match)
138+
rm -rf public/ resources/
139+
npm run build
140+
141+
.PHONY: clean-nuclear
142+
clean-nuclear: ## Full wipe (Hugo output, Hugo cache, node_modules) + fresh npm ci + rebuild
143+
rm -rf public/ resources/ /tmp/hugo_cache/ node_modules/
144+
npm ci
145+
npm run build
146+
147+
.PHONY: reset-sync
148+
reset-sync: ## Clear all generated sync content + full rebuild (use when sync logic or upstream changes)
149+
rm -f .sync-manifest.json data/projects.json
150+
rm -rf content/docs/projects/*/
151+
rm -rf public/ resources/
152+
go run ./cmd/sync-content $(SYNC_FLAGS) --lock $(LOCK) --write
153+
npm run build

‎README.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -8,7 +8,7 @@ Built with [Hugo](https://gohugo.io/) and the [Doks](https://getdoks.org/) theme
88

99
```bash
1010
npm install
11-
go run ./cmd/sync-content --org complytime --config sync-config.yaml --write
11+
make sync # or: go run ./cmd/sync-content --org complytime --config sync-config.yaml --write
1212
npm run dev
1313
```
1414

‎cmd/sync-content/README.md‎

Lines changed: 11 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -61,7 +61,17 @@ For setup, prerequisites, and day-to-day commands, see
6161
[CONTRIBUTING.md](../../CONTRIBUTING.md#development-workflow). For the full CLI
6262
flag reference, see the [spec](../../specs/006-go-sync-tool/spec.md#cli-interface).
6363

64-
The essentials:
64+
The essentials (using the Makefile at the repo root — run `make help` for a full list):
65+
66+
```bash
67+
make sync-dry # dry-run: reads GitHub, writes nothing
68+
make sync # apply changes to disk
69+
make sync-single REPO=complytime/complyctl # single-repo apply
70+
make test-race # run tests with race detector
71+
make check # vet + fmt-check + race tests
72+
```
73+
74+
Equivalent raw commands:
6575

6676
```bash
6777
go run ./cmd/sync-content --org complytime --config sync-config.yaml # dry-run

‎layouts/_markup/render-codeblock-kroki.html‎

Lines changed: 114 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,114 @@
1+
{{- /* Last modified: 2023-06-30T12:24:14-07:00 */}}
2+
3+
{{- /*
4+
Copyright 2023 Veriphor LLC
5+
6+
Licensed under the Apache License, Version 2.0 (the "License"); you may not
7+
use this file except in compliance with the License. You may obtain a copy of
8+
the License at
9+
10+
https://www.apache.org/licenses/LICENSE-2.0
11+
12+
Unless required by applicable law or agreed to in writing, software
13+
distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
14+
WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
15+
License for the specific language governing permissions and limitations under
16+
the License.
17+
*/}}
18+
19+
{{- /*
20+
Renders an SVG image of a diagram from a textual description using the Kroki service.
21+
22+
Local override of @thulite/doks-core: fixes output_format "SVG" → "svg" (kroki.io
23+
requires lowercase per its API) and downgrades network fetch failures from errorf
24+
to warnf so a remote service outage does not abort the build.
25+
26+
References:
27+
28+
- https://kroki.io/
29+
- https://kroki.io/#examples
30+
31+
@context {map} Attributes The markdown attributes from the info string.
32+
@context {string} Inner The content between the leading and trailing code fences, excluding the info string.
33+
@context {map} Options The highlighting options from the info string.
34+
@context {int} Ordinal The zero-based ordinal of the code block on the page.
35+
@context {page} Page A reference to the page containing the code block.
36+
@context {text.Position} Position The position of the code block within the page content.
37+
@context {string} Type The first word of the info string.
38+
39+
@param {string} Attributes.type The type of diagram to render
40+
41+
@returns {template.html}
42+
*/}}
43+
44+
{{- /* Initialize. */}}
45+
{{- $renderHookName := "kroki" }}
46+
47+
{{- /* Verify minimum required version. */}}
48+
{{- $minHugoVersion := "0.141.0" }}
49+
{{- if lt hugo.Version $minHugoVersion }}
50+
{{- errorf "The %q code block render hook requires Hugo v%s or later." $renderHookName $minHugoVersion }}
51+
{{- end }}
52+
53+
{{- /* Get context. */}}
54+
{{- $attrs := .Attributes }}
55+
{{- $inner := trim .Inner "\n\r" }}
56+
{{- $ordinal := .Ordinal }}
57+
{{- $position := .Position }}
58+
59+
{{- /* Initialize. */}}
60+
{{- $apiEndpoint := or site.Params.doks.krokiURL "https://kroki.io/" }}
61+
{{- $diagramType := $attrs.type | lower }}
62+
63+
{{- /* Validate diagram type. */}}
64+
{{- $supportedTypes := slice
65+
"actdiag" "blockdiag" "bpmn" "bytefield" "ditaa" "d2" "dbml" "erd" "graphviz"
66+
"mermaid" "nomnoml" "nwdiag" "packetdiag" "pikchr" "plantuml" "rackdiag"
67+
"seqdiag" "structurizr" "svgbob" "umlet" "vega" "vegalite" "wavedrom"
68+
"wireviz"
69+
}}
70+
{{- $typesDelimited := delimit $supportedTypes ", " ", and " }}
71+
{{- if not (in $supportedTypes $diagramType) }}
72+
{{- errorf "The %q code block render hook does not support diagram type %q. Valid types are %s. See %s" $renderHookName $attrs.type $typesDelimited $position }}
73+
{{- end }}
74+
75+
{{- /* Determine class attribute. */}}
76+
{{- $class := printf "diagram diagram-kroki diagram-kroki-%s" $diagramType }}
77+
{{- with $attrs.class }}
78+
{{- $class = printf "%s %s" $class . }}
79+
{{- end }}
80+
81+
{{- /* Determine id attribute. */}}
82+
{{- $id := printf "h-rh-cb-kroki-%d" $ordinal }}
83+
{{- with $attrs.id }}
84+
{{- $id = . }}
85+
{{- end }}
86+
87+
{{- /* Merge class and id attributes. */}}
88+
{{- $attrs = merge $attrs (dict "class" $class "id" $id "alt" "diagram") }}
89+
90+
{{- /* Get diagram. Fix 1: "svg" lowercase (upstream bug sends "SVG" which kroki.io rejects).
91+
Fix 2: warnf instead of errorf so network failures do not abort the build. */}}
92+
{{- $body := dict "diagram_source" $inner "diagram_type" $diagramType "output_format" "svg" | jsonify }}
93+
{{- $opts := dict "method" "post" "body" $body }}
94+
{{- with try (resources.GetRemote $apiEndpoint $opts) }}
95+
{{- with .Err }}
96+
{{- warnf "The %q code block render hook was unable to get the remote diagram. See %s. %s" $renderHookName $position . }}
97+
{{- else with .Value }}
98+
{{- $attrs = merge $attrs (dict "src" .RelPermalink) }}
99+
{{- else }}
100+
{{- warnf "The %q code block render hook was unable to get the remote diagram. See %s" $renderHookName $position }}
101+
{{- end }}
102+
{{- end }}
103+
104+
{{- /* Render. */}}
105+
<img
106+
{{- range $k, $v := $attrs }}
107+
{{- if not (eq $k "type") }}
108+
{{- if $v }}
109+
{{- printf " %s=%q" $k (string $v) | safeHTMLAttr }}
110+
{{- end }}
111+
{{- end }}
112+
{{- end -}}
113+
>
114+
{{- /**/ -}}

0 commit comments

Comments
 (0)