Skip to content

Commit

Permalink
Improve docs generation
Browse files Browse the repository at this point in the history
- Filter out openapi category
- Delete files before generation, making category renames possible
- Print the menu only if the summary has changed
  • Loading branch information
tinygrasshopper committed May 31, 2024
1 parent cb7c54f commit fb218d4
Show file tree
Hide file tree
Showing 3 changed files with 47 additions and 2 deletions.
1 change: 1 addition & 0 deletions tools/api-docs-generator/config.yml
Original file line number Diff line number Diff line change
Expand Up @@ -12,4 +12,5 @@ categoryContext:
hint: |
**Note:** When you import or update Projects, changes will be reflected in the endpoint results after a one-hour delay.
output:
summaryPath: docs/SUMMARY.md
apiReferencePath: docs/snyk-api/reference
1 change: 1 addition & 0 deletions tools/api-docs-generator/config/config.go
Original file line number Diff line number Diff line change
Expand Up @@ -18,6 +18,7 @@ type Spec struct {
}

type Output struct {
SummaryPath string `yaml:"summaryPath"`
APIReferencePath string `yaml:"apiReferencePath"`
}

Expand Down
47 changes: 45 additions & 2 deletions tools/api-docs-generator/generator/reference_docs.go
Original file line number Diff line number Diff line change
Expand Up @@ -29,6 +29,11 @@ func GenerateReferenceDocs(cfg *config.Config, docsBasePath string) error {
}

summary := make([]string, len(aggregatedDocs))
err = clearDir(path.Join(docsBasePath, cfg.Output.APIReferencePath))
if err != nil {
return err
}

for label, operations := range aggregatedDocs {
destinationPath := path.Join(docsBasePath, cfg.Output.APIReferencePath, labelToFileName(label))
summary = append(summary, fmt.Sprintf("* [%s](%s)\n", label, path.Join(cfg.Output.APIReferencePath, labelToFileName(label))))
Expand All @@ -39,9 +44,44 @@ func GenerateReferenceDocs(cfg *config.Config, docsBasePath string) error {
}
}
sort.Strings(summary)
fmt.Printf("generated menu for summary:\n")
fmt.Printf("%s", strings.Join(summary, ""))

matches, err := matchCurrentSummary(cfg.Output.SummaryPath, summary)
if !matches {
fmt.Printf("generated menu for summary:\n")
fmt.Printf("%s", strings.Join(summary, ""))
}

return nil
}

func matchCurrentSummary(summaryPath string, summary []string) (bool, error) {
contents, err := os.ReadFile(summaryPath)
if err != nil {
return false, fmt.Errorf("failed to read summary file: %w", err)
}
currentSummary := string(contents)
for _, menuItem := range summary {
if !strings.Contains(currentSummary, menuItem) {
return false, nil
}
}
return true, nil
}

func clearDir(dirName string) error {
dir, err := os.ReadDir(dirName)
if err != nil {
return err
}
for _, child := range dir {
if strings.HasPrefix(child.Name(), "README") {
continue
}
err = os.RemoveAll(path.Join(dirName, child.Name()))
if err != nil {
return err
}
}
return nil
}

Expand All @@ -57,6 +97,9 @@ func aggregateSpecs(cfg *config.Config, docsBasePath string) (map[string][]opera
for pathURL, pathItem := range doc.Paths.Map() {
for method, operation := range pathItem.Operations() {
for _, tag := range operation.Tags {
if tag == "OpenAPI" {
continue
}
tag += spec.Suffix
aggregatedDocs[tag] = append(aggregatedDocs[tag], operationPath{
operation: operation,
Expand Down

0 comments on commit fb218d4

Please sign in to comment.