Skip to content

Commit 938450a

Browse files
alovnalovn
committed
feat: add output-index args to generate custom index file name
1 parent bedb21a commit 938450a

File tree

12 files changed

+50
-33
lines changed

12 files changed

+50
-33
lines changed

‎README.md

Lines changed: 10 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -15,14 +15,15 @@ $ apidocgen --help
1515
apidocgen is a tool for Go to generate apis markdown docs.
1616

1717
Usage:
18-
apidocgen --dir= --excludes= --output= --template= --single
18+
apidocgen --dir= --excludes= --output= --output-index= --template= --single
1919

2020
Flags:
21-
--dir: Search apis dir, comma separated, default .
22-
--excludes: Exclude directories and files when searching, comma separated
23-
--output: Generate markdown files dir, default ./docs/
24-
--template: Template name or custom template directory, built-in includes markdown and apidocs, default markdown.
25-
--single: Generate a single markdown file.
21+
--dir: Search apis dir, comma separated, default .
22+
--excludes: Exclude directories and files when searching, comma separated
23+
--output: Generate markdown files dir, default ./docs/
24+
--output-index: Generate index file name.
25+
--template: Template name or custom template directory, built-in includes markdown and apidocs, default markdown.
26+
--single: Generate a single markdown file.
2627
```
2728

2829
built-in templates include `markdown` and `apidocs`, default is `markdown`.
@@ -39,6 +40,9 @@ apidocgen \
3940
--dir=svc-user,common \
4041
--template=apidocs \
4142
--output=./docs
43+
44+
apidocgen --output-index=index.md //generate index.md
45+
apidocgen --output-index=@{service}.md //generate index file name by your @service comment, example: svc-user.md.
4246
```
4347

4448
## Template

‎examples/docs/README.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -48,5 +48,5 @@ version: [email protected]_
4848
5.7. [time](./apis-demo.md#7-time)
4949

5050
<p align="right">
51-
<a href="https://github.com/alovn/apidocgen" style="color:gray;">Generated by apidocgen</a>
51+
<a href="https://github.com/alovn/apidocgen" style="color:#ccc;" target="_blank">Generated by apidocgen</a>
5252
</p>

‎examples/docs/apis-account.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -101,5 +101,5 @@ __Response__:
101101
---
102102

103103
<p align="right">
104-
<a href="https://github.com/alovn/apidocgen" style="color:gray;">Generated by apidocgen</a>
104+
<a href="https://github.com/alovn/apidocgen" style="color:#ccc;" target="_blank">Generated by apidocgen</a>
105105
</p>

‎examples/docs/apis-address.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -163,5 +163,5 @@ __Response__:
163163
---
164164

165165
<p align="right">
166-
<a href="https://github.com/alovn/apidocgen" style="color:gray;">Generated by apidocgen</a>
166+
<a href="https://github.com/alovn/apidocgen" style="color:#ccc;" target="_blank">Generated by apidocgen</a>
167167
</p>

‎examples/docs/apis-demo.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -226,5 +226,5 @@ __Response__:
226226
---
227227

228228
<p align="right">
229-
<a href="https://github.com/alovn/apidocgen" style="color:gray;">Generated by apidocgen</a>
229+
<a href="https://github.com/alovn/apidocgen" style="color:#ccc;" target="_blank">Generated by apidocgen</a>
230230
</p>

‎examples/docs/apis-menu.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -39,5 +39,5 @@ __Response__:
3939
---
4040

4141
<p align="right">
42-
<a href="https://github.com/alovn/apidocgen" style="color:gray;">Generated by apidocgen</a>
42+
<a href="https://github.com/alovn/apidocgen" style="color:#ccc;" target="_blank">Generated by apidocgen</a>
4343
</p>

‎examples/docs/apis-profile.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -35,5 +35,5 @@ __Response__:
3535
---
3636

3737
<p align="right">
38-
<a href="https://github.com/alovn/apidocgen" style="color:gray;">Generated by apidocgen</a>
38+
<a href="https://github.com/alovn/apidocgen" style="color:#ccc;" target="_blank">Generated by apidocgen</a>
3939
</p>

‎gen/gen.go

Lines changed: 22 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -22,6 +22,7 @@ type Gen struct {
2222
type Config struct {
2323
SearchDir string
2424
OutputDir string
25+
OutputIndexName string
2526
TemplateDir string
2627
ExcludesDir string
2728
IsGenSingleFile bool
@@ -58,37 +59,37 @@ func (g *Gen) readTemplate(name string) (s string, err error) {
5859

5960
func (g *Gen) Build() error {
6061
if g.c == nil {
61-
return errors.New("error config")
62+
return errors.New("error: config nil")
6263
}
64+
6365
searchDirs := strings.Split(g.c.SearchDir, ",")
6466
for _, searchDir := range searchDirs {
6567
if _, err := os.Stat(searchDir); os.IsNotExist(err) {
66-
return fmt.Errorf("dir: %s does not exist", searchDir)
68+
return fmt.Errorf("error: dir %s does not exist", searchDir)
6769
}
6870
}
71+
6972
var err error
7073
if strings.ContainsAny(g.c.TemplateDir, "/\\") { //custom dir
7174
g.templateFS = os.DirFS(g.c.TemplateDir)
75+
} else {
76+
g.c.TemplateDir = fmt.Sprintf("template/%s", g.c.TemplateDir)
7277
if g.templateFS, err = fs.Sub(defaultTemplateFS, g.c.TemplateDir); err != nil {
7378
return err
7479
}
75-
} else {
76-
g.c.TemplateDir = fmt.Sprintf("template/%s", g.c.TemplateDir)
77-
}
78-
if g.templateFS, err = fs.Sub(defaultTemplateFS, g.c.TemplateDir); err != nil {
79-
return err
8080
}
8181

82-
var templateConfig TemplateConfig
83-
if s, err := g.readTemplate("config.json"); err != nil {
84-
return err
85-
} else {
82+
if s, err := g.readTemplate("config.json"); err == nil {
83+
var templateConfig TemplateConfig
8684
if err = json.Unmarshal([]byte(s), &templateConfig); err != nil {
8785
return err
8886
}
8987
if templateConfig.Index == "" {
9088
templateConfig.Index = "README.md"
9189
}
90+
if g.c.OutputIndexName == "" {
91+
g.c.OutputIndexName = templateConfig.Index
92+
}
9293
fmt.Println("use template:", templateConfig.Name)
9394
}
9495

@@ -111,6 +112,11 @@ func (g *Gen) Build() error {
111112
return nil
112113
}
113114

115+
g.c.OutputIndexName = strings.ReplaceAll(g.c.OutputIndexName, "@{service}", doc.Service)
116+
if strings.ContainsAny(g.c.OutputIndexName, "/\\") { //custom dir
117+
return fmt.Errorf("error: output-index can't be a directory: %s.", g.c.OutputIndexName)
118+
}
119+
114120
if len(doc.UngroupedApis) > 0 {
115121
doc.Groups = append(doc.Groups, &parser.ApiGroupSpec{
116122
Group: "ungrouped",
@@ -120,6 +126,7 @@ func (g *Gen) Build() error {
120126
})
121127
doc.UngroupedApis = doc.UngroupedApis[:0]
122128
}
129+
123130
sort.Slice(doc.Groups, func(i, j int) bool {
124131
a, b := doc.Groups[i], doc.Groups[j]
125132
if a.Order == b.Order {
@@ -150,7 +157,7 @@ func (g *Gen) Build() error {
150157
return err
151158
}
152159
if g.c.IsGenSingleFile {
153-
f, err := os.Create(filepath.Join(g.c.OutputDir, templateConfig.Index))
160+
f, err := os.Create(filepath.Join(g.c.OutputDir, g.c.OutputIndexName))
154161
if err != nil {
155162
return err
156163
}
@@ -162,7 +169,7 @@ func (g *Gen) Build() error {
162169
if err = t.ExecuteTemplate(f, "single_index", doc); err != nil {
163170
return err
164171
}
165-
fmt.Println("generated: ", templateConfig.Index)
172+
fmt.Println("generated: ", g.c.OutputIndexName)
166173
} else {
167174
//group
168175
for _, v := range doc.Groups {
@@ -180,15 +187,15 @@ func (g *Gen) Build() error {
180187
fmt.Println("Generated:", fileName)
181188
}
182189
//readme
183-
f, err := os.Create(filepath.Join(g.c.OutputDir, templateConfig.Index))
190+
f, err := os.Create(filepath.Join(g.c.OutputDir, g.c.OutputIndexName))
184191
if err != nil {
185192
return err
186193
}
187194
defer f.Close()
188195
if err = t.ExecuteTemplate(f, "group_index", doc); err != nil {
189196
return err
190197
}
191-
fmt.Println("generated:", templateConfig.Index)
198+
fmt.Println("generated:", g.c.OutputIndexName)
192199
}
193200
fmt.Println("apis total count:", doc.TotalCount)
194201
return nil

‎gen/template/apidocs/footer.tpl

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
{{- define "footer" }}
22
<p align="right">
3-
<a href="https://github.com/alovn/apidocgen" style="color:gray;">Generated by apidocgen</a>
3+
<a href="https://github.com/alovn/apidocgen" style="color:#ccc;" target="_blank">Generated by apidocgen</a>
44
</p>
55
{{- end }}

‎gen/template/apidocs/group_index.tpl

Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -15,9 +15,11 @@ version: _@{{.Version}}_
1515

1616
{{.Description}}
1717
{{- end}}
18-
{{range $k,$v := .Groups}}
18+
{{- range $k,$v := .Groups}}
19+
1920
{{add $k 1}}. [{{$v.Title}}](./apis-{{$v.Group}})
20-
{{range $k2,$api := $v.Apis}}
21+
{{- range $k2,$api := $v.Apis}}
22+
2123
{{add $k 1}}.{{add $k2 1}}. [{{$api.Title}}](./apis-{{$api.Group}}#{{add $k2 1}}-{{$api.Title}}) {{- if $api.Deprecated}}(Deprecated){{end}}
2224
{{- end }}
2325
{{- end }}

0 commit comments

Comments
 (0)