From 6012bbcb5a2d7aec537f58dd2a1b3994e410b18a Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?M=C3=A1ximo=20Cuadros?= <mcuadros@gmail.com>
Date: Sun, 22 Mar 2020 13:49:24 +0100
Subject: [PATCH] doc: templates, examples support and Type styling

---
 Makefile             |  5 +++-
 _scripts/template.md | 57 ++++++++++++++++++++++++++++++++++----------
 2 files changed, 49 insertions(+), 13 deletions(-)

diff --git a/Makefile b/Makefile
index d76c93e..9683827 100644
--- a/Makefile
+++ b/Makefile
@@ -7,9 +7,11 @@ DEPENDENCIES =
 OUTLINE_CMD ?= outline
 DOCUMENTATION_PATH ?= _documentation
 DOCUMENTATION_RUNTIME_PATH ?= $(DOCUMENTATION_PATH)/runtime
+EXAMPLES_PATH ?= starlark/types/testdata/examples
 
 RUNTIME_MODULES = \
 	github.com/mcuadros/ascode/starlark/module/os \
+	github.com/mcuadros/ascode/starlark/types \
 	github.com/mcuadros/ascode/starlark/module/filepath \
 	github.com/qri-io/starlib/encoding/base64 \
 	github.com/qri-io/starlib/encoding/csv \
@@ -50,7 +52,8 @@ BIN_PATH := $(BUILD_PATH)/bin
 
 documentation: $(RUNTIME_MODULES)
 $(RUNTIME_MODULES): $(DOCUMENTATION_RUNTIME_PATH)
-	@$(OUTLINE_CMD) package -t _scripts/template.md $@ > $(DOCUMENTATION_RUNTIME_PATH)/`basename $@`.md
+	$(OUTLINE_CMD) package -t _scripts/template.md -d $(EXAMPLES_PATH) $@ \
+		> $(DOCUMENTATION_RUNTIME_PATH)/`basename $@`.md
 
 $(DOCUMENTATION_RUNTIME_PATH):
 	mkdir -p $@
diff --git a/_scripts/template.md b/_scripts/template.md
index 0062a72..981451b 100644
--- a/_scripts/template.md
+++ b/_scripts/template.md
@@ -1,8 +1,17 @@
-{{- define "mdFn" }}
+{{- define "functionName" }}
+{{- if ne .Receiver "types" -}}
+#
+{{- end -}}
+### def {{ if ne .Receiver "types" -}}
+	 <i>{{ .Receiver }}</i>.
+	{{- end -}}
+	<b>{{- (index (split .Signature "(") 0) -}}</b>
+{{- end -}}
+{{- define "function" }}
 
-#### def <b>{{ (index (split .Signature "(") 0) }}</b>
+{{ template "functionName" . }}
 ```go
-{{ .Signature }}
+{{if ne .Receiver "types" -}}{{.Receiver}}.{{- end }}{{ .Signature }}
 ```
 
 {{- if ne .Description "" }}
@@ -11,15 +20,26 @@
 
 {{- if gt (len .Params) 0 }}
 
-**parameters:**
+###### Arguments
 
 | name | type | description |
 |------|------|-------------|
 {{ range .Params -}}
-| '{{ .Name }}' | '{{ .Type }}' | {{ .Description }} |
+| `{{ .Name }}` | `{{ .Type }}` | {{ .Description }} |
 {{ end -}}
 
 {{- end -}}
+
+{{- if gt (len .Examples) 0 }}
+
+{{ range .Examples -}}
+```python
+{{ .Code }}
+```
+{{ end -}}
+
+{{- end -}}
+
 {{- end -}}
 
 {{- range . -}}
@@ -32,7 +52,7 @@ title: '{{ .Path }}'
 {{- if gt (len .Functions) 0 }}
 ## Functions
 {{ range .Functions -}}
-{{ template "mdFn" . }}
+{{ template "function" . }}
 {{ end -}}
 {{- end }}
 
@@ -41,29 +61,41 @@ title: '{{ .Path }}'
 {{ range .Types -}}
 
 
-### '{{ .Name }}'
+### <b>{{ .Name }}</b>
 {{ if ne .Description "" }}{{ .Description }}{{ end -}}
 {{ if gt (len .Fields) 0 }}
 
-**Fields**
+###### Properties
 
 | name | type | description |
 |------|------|-------------|
 {{ range .Fields -}}
-| {{ .Name }} | {{ .Type }} | {{ .Description }} |
+| `{{ .Name }}` | `{{ .Type }}` | {{ .Description }} |
 {{ end -}}
 
+{{ if gt (len .Examples) 0 }}
+###### Examples
+{{ range .Examples -}}
+{{ .Description }}
+```python
+{{ .Code }}
+```
 {{ end -}}
+{{ end -}}
+
+
+{{ end -}}
+
 {{ if gt (len .Methods) 0 }}
 
-**Methods**
+###### Methods
 
 {{- range .Methods -}}
-{{ template "mdFn" . }}
+{{ template "function" . }}
 {{ end -}}
 {{- if gt (len .Operators) 0 }}
 
-**Operators**
+###### Operators
 
 | operator | description |
 |----------|-------------|
@@ -72,6 +104,7 @@ title: '{{ .Path }}'
 {{ end }}
 
 {{ end }}
+
 {{ end }}
 {{- end -}}
 {{- end -}}