Skip to content

Commit 14c26f7

Browse files
tmctmc
committed
protoc-gen-apidocs: Separate hugo-specific output
1 parent ffba008 commit 14c26f7

File tree

2 files changed

+177
-1
lines changed

2 files changed

+177
-1
lines changed

‎main.go

+31-1
Original file line numberDiff line numberDiff line change
@@ -49,7 +49,8 @@ type GenOpts struct {
4949
}
5050

5151
var formatFileSuffixes = map[string]string{
52-
"markdown": "md",
52+
"markdown": "md",
53+
"hugo-markdown": "md",
5354
}
5455

5556
// generateFile generates a _ascii.pb.go file containing gRPC service definitions.
@@ -66,6 +67,19 @@ func (o *GenOpts) generateFile(gen *protogen.Plugin, file *protogen.File) error
6667
return nil
6768
}
6869

70+
func (o *GenOpts) relPath(t1, t2 protoreflect.Descriptor) string {
71+
path := ""
72+
cpf := filepath.Base(fmt.Sprint(t1.ParentFile().Path()))
73+
rpf := filepath.Base(fmt.Sprint(t2.ParentFile().Path()))
74+
if cpf != rpf {
75+
path, _ = filepath.Rel(cpf, rpf)
76+
path = strings.TrimSuffix(path, filepath.Ext(path))
77+
path = strings.TrimPrefix(path, ".")
78+
path = fmt.Sprintf("%s.%s", path, formatFileSuffixes[o.Format])
79+
}
80+
return path
81+
}
82+
6983
func longName(d protoreflect.Descriptor) string {
7084
p := d.Parent()
7185
if p != nil && p.Parent() != nil {
@@ -125,6 +139,22 @@ func (o *GenOpts) templateFuncMap() template.FuncMap {
125139
return false
126140
},
127141
"type_link": func(f *protogen.Field) string {
142+
var t1, t2 protoreflect.Descriptor
143+
t1 = f.Desc
144+
if f.Message != nil {
145+
t2 = f.Message.Desc
146+
}
147+
if f.Enum != nil {
148+
t2 = f.Enum.Desc
149+
}
150+
if strings.HasPrefix(string(t2.FullName()), "google.") {
151+
return string(t2.FullName())
152+
}
153+
fn := o.relPath(t1, t2)
154+
typ := anchor(fmt.Sprint(t2.FullName()))
155+
return fmt.Sprintf(`%s#%s`, fn, typ)
156+
},
157+
"type_link_hugo": func(f *protogen.Field) string {
128158
// exclude google types:
129159

130160
if f.Message != nil {

‎templates/hugo-markdown.tmpl

+146
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,146 @@
1+
{{/***************************************************************
2+
Markdown template for protoc-gen-apidocs
3+
4+
This template is rendered once per incoming .proto file and
5+
defines the resulting output documentation.
6+
7+
This file is organized into blocks via the go template "define"
8+
function and they are executed with the "template" function.
9+
***************************************************************/}}
10+
11+
{{/***************************************************************
12+
Main output block
13+
***************************************************************/}}
14+
{{define "output" -}}
15+
16+
---
17+
title: {{ .Desc.Package }}
18+
description: API Specification for the {{ .Desc.Package }} package.
19+
---
20+
21+
<a name="{{.Desc.Path |base | anchor}}"></a><p align="right"><a href="#top">Top</a></p>
22+
23+
<!-- begin services -->
24+
{{range .Services}}
25+
{{template "service" .}}
26+
{{end}}
27+
<!-- begin services -->
28+
29+
{{ range .Messages }}
30+
{{template "message" .}}
31+
{{end}} <!-- end messages -->
32+
33+
<!-- begin file-level enums -->
34+
{{range .Enums}}
35+
{{template "enum" .}}
36+
{{end}} <!-- end file-level enums -->
37+
38+
<!-- begin file-level extensions -->
39+
{{if .Extensions}}
40+
<a name="{{.Desc.Path |base | anchor}}-extensions"></a>
41+
42+
### Extensions
43+
| Extension | Type | Extension Point | Number | Description |
44+
| --------- | ---- | ---- | ------ | ----------- |
45+
{{range .Extensions -}}
46+
| {{.Desc.Name}} | {{.Desc.FullName}} | {{ .Extendee | message_type }} | {{.Desc.Number}} | {{ .Comments.Leading | description | nobr}} {{ .Comments.Trailing | description | nobr}} |
47+
{{end}}
48+
{{end}} <!-- end file-level extensions -->
49+
50+
{{end}}
51+
52+
53+
{{/***************************************************************
54+
Service template
55+
***************************************************************/}}
56+
{{define "service"}}
57+
<a name="{{.Desc.FullName | anchor}}"></a>
58+
59+
### {{.Desc.Name}}
60+
61+
{{.Comments.Leading | description}}
62+
{{.Comments.Trailing | description}}
63+
64+
| Method Name | Request Type | Response Type | Description |
65+
| ----------- | ------------ | ------------- | ------------|
66+
{{range .Methods -}}
67+
| {{.Desc.Name}} | [{{ .Input | message_type }}](#{{ .Input | full_message_type | anchor }}) | [{{ .Output | message_type }}](#{{ .Output | full_message_type | anchor }}){{if .Desc.IsStreamingServer}} stream{{end}} | {{ .Comments.Leading | description | nobr}} {{ .Comments.Trailing | description | nobr}} |
68+
{{end}}
69+
{{end}}
70+
71+
72+
73+
{{/***************************************************************
74+
Message template
75+
***************************************************************/}}
76+
{{define "message"}}
77+
<a name="{{.Desc.FullName | anchor}}"></a>
78+
79+
### {{.Desc.Name}}
80+
81+
{{.Comments.Leading | description}}
82+
{{.Comments.Trailing | description}}
83+
84+
{{if .Fields}}
85+
| Field | Type | Description |
86+
| ----- | ---- | ----------- |
87+
{{range .Fields}}{{ if (not .Desc.ContainingOneof) }}{{template "field" .}}{{end}}{{end}}
88+
{{- end -}}
89+
{{range .Oneofs}}{{template "oneof" .}}{{end}}
90+
91+
{{if .Extensions}}
92+
| Extension | Type | Base | Number | Description |
93+
| --------- | ---- | ---- | ------ | ----------- |
94+
{{range .Extensions -}}
95+
| {{.Desc.Name}} | {{.Desc | long_name}} | {{.Parent | message_type}} | {{.Desc.Number}} | {{ .Comments.Leading | description | nobr}} {{ .Comments.Trailing | description | nobr}} |
96+
{{end}}
97+
{{end}}
98+
99+
{{ range .Messages }}
100+
{{template "message" .}}
101+
{{end}} <!-- end nested messages -->
102+
103+
{{range .Enums}}
104+
{{template "enum" .}}
105+
{{end}} <!-- end nested enums -->
106+
107+
{{end}}
108+
109+
{{/***************************************************************
110+
Field template
111+
***************************************************************/}}
112+
{{define "field" -}}
113+
| {{.Desc.Name}}{{ if .Desc.IsList }}[]{{ end }} |
114+
{{- if (or (is_primitive .) (is_google_type .)) -}}
115+
{{ field_type . }}
116+
{{- else -}}
117+
[{{ .| field_type }}]({{ hugo_type_link . }})
118+
{{- end -}}
119+
| {{ .Comments.Leading | description | nobr}} {{ .Comments.Trailing | description | nobr }} |
120+
{{end}}
121+
122+
{{/***************************************************************
123+
Oneof template
124+
This is kind of gross since GFM doesn't support colspan.
125+
***************************************************************/}}
126+
{{define "oneof" -}}
127+
|<tr><td colspan=2>Union field `{{ .Desc.Name }}`. {{ .Comments.Leading | description | nobr}} {{ .Comments.Trailing | description | nobr }} `{{ .Desc.Name }}` can be only one of the following:</td></tr>|
128+
{{range .Fields}}{{template "field" .}}{{end}}
129+
{{end}}
130+
131+
{{/***************************************************************
132+
Enum template
133+
***************************************************************/}}
134+
{{define "enum" }}
135+
<a name="{{.Desc.FullName | anchor}}"></a>
136+
137+
### {{.Desc | long_name}}
138+
{{.Comments.Leading | description}}
139+
{{.Comments.Trailing | description}}
140+
141+
| Name | Number | Description |
142+
| ---- | ------ | ----------- |
143+
{{range .Values -}}
144+
| {{.Desc.Name}} | {{.Desc.Number}} | {{ .Comments.Leading | description | nobr}} {{ .Comments.Trailing | description | nobr}} |
145+
{{end}}
146+
{{end}}

0 commit comments

Comments
 (0)