From 4550badf582e832f3cc539c6bd41b6fc94cd1758 Mon Sep 17 00:00:00 2001
From: Michael McLoughlin <mmcloughlin@gmail.com>
Date: Mon, 31 Dec 2018 20:25:29 -0800
Subject: [PATCH] doc: scripts to run embedmd on markdown files

This will help keep READMEs in sync with code.

Also adds a README for the add example.

Updates #14
---
 examples/add/README.md | 49 ++++++++++++++++++++++++++++++++++++++++++
 script/bootstrap       |  3 +++
 script/doc             |  3 +++
 script/generate        |  5 ++++-
 4 files changed, 59 insertions(+), 1 deletion(-)
 create mode 100644 examples/add/README.md
 create mode 100755 script/doc

diff --git a/examples/add/README.md b/examples/add/README.md
new file mode 100644
index 0000000..e35040f
--- /dev/null
+++ b/examples/add/README.md
@@ -0,0 +1,49 @@
+# add
+
+Add two numbers with `avo`.
+
+The [code generator](asm.go) is as follows:
+
+[embedmd]:# (asm.go)
+```go
+// +build ignore
+
+package main
+
+import (
+	. "github.com/mmcloughlin/avo/build"
+)
+
+func main() {
+	TEXT("Add", "func(x, y uint64) uint64")
+	Doc("Add adds x and y.")
+	x := Load(Param("x"), GP64v())
+	y := Load(Param("y"), GP64v())
+	ADDQ(x, y)
+	Store(y, ReturnIndex(0))
+	RET()
+	Generate()
+}
+```
+
+We use a [`go:generate`](https://blog.golang.org/generate) line to produce the assembly and Go stub files together.
+
+[embedmd]:# (add_test.go go /.*go:generate.*/)
+```go
+//go:generate go run asm.go -out add.s -stubs stub.go
+```
+
+This produces [`add.s`](add.s) as follows:
+
+[embedmd]:# (add.s)
+```s
+// Code generated by command: go run asm.go -out add.s -stubs stub.go. DO NOT EDIT.
+
+// func Add(x uint64, y uint64) uint64
+TEXT ·Add(SB), $0-24
+	MOVQ	x(FP), AX
+	MOVQ	y+8(FP), CX
+	ADDQ	AX, CX
+	MOVQ	CX, ret+16(FP)
+	RET
+```
diff --git a/script/bootstrap b/script/bootstrap
index 79aaf8a..dff10b3 100755
--- a/script/bootstrap
+++ b/script/bootstrap
@@ -8,3 +8,6 @@ go get -u \
 # Install golangci-lint
 golangci_lint_version='v1.12.3'
 curl -sfL https://install.goreleaser.com/github.com/golangci/golangci-lint.sh | sh -s -- -b $GOPATH/bin ${golangci_lint_version}
+
+# embedmd required for documentation generation
+go get -u github.com/campoy/embedmd
diff --git a/script/doc b/script/doc
new file mode 100755
index 0000000..6211ae6
--- /dev/null
+++ b/script/doc
@@ -0,0 +1,3 @@
+#!/bin/bash -ex
+
+find . -name '*.md' | xargs embedmd -w
diff --git a/script/generate b/script/generate
index 337c1be..52c77f1 100755
--- a/script/generate
+++ b/script/generate
@@ -8,7 +8,7 @@ post=$(go list ./... | grep -E  'avo/(examples|tests)')
 go install ./internal/cmd/avogen
 
 # Attempt to delete generated files, to prove we can recreate them.
-grep -REl 'Code generated.*DO NOT EDIT\.$' . | xargs rm -v
+grep -REl 'Code generated.*DO NOT EDIT\.$' . | grep -v '.md$' | xargs rm -v
 
 # Generate once.
 go generate -v -x ${core}
@@ -19,3 +19,6 @@ go generate -v -x ${core}
 
 # Generate dependent packages.
 go generate -v -x ${post}
+
+# Regenerate documentation.
+./script/doc