From e0c5cd02e4e06ac3499d66b9cf813a36c8005b0c Mon Sep 17 00:00:00 2001 From: sheidkamp Date: Thu, 14 Nov 2024 13:18:33 -0500 Subject: [PATCH 1/5] Update template_funcs.go --- pkg/code-generator/docgen/funcs/template_funcs.go | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/pkg/code-generator/docgen/funcs/template_funcs.go b/pkg/code-generator/docgen/funcs/template_funcs.go index 59d4063eb..1c566e6d9 100644 --- a/pkg/code-generator/docgen/funcs/template_funcs.go +++ b/pkg/code-generator/docgen/funcs/template_funcs.go @@ -318,8 +318,13 @@ func linkForField(project *model.Project, docsOptions *options.DocsOptions) func linkedFile = filepath.Base(file.GetName()) //return "", errors.Errorf("failed to get generated file path for proto %v in list %v", file.GetName(), project.Request.FileToGenerate) } - linkedFile = relativeFilename(forFile.GetName(), linkedFile) + // Don't link to external apis docs, as they will be deleted + if strings.HasPrefix(linkedFile, "github.com/solo-io/gloo/projects/gloo/api/external") { + return typeName, nil + } + + linkedFile = relativeFilename(forFile.GetName(), linkedFile) if docsOptions.Output == options.Restructured { linkText = ":ref:`message." + strings.TrimPrefix(field.GetTypeName(), ".") + "`" } else { From 5e2965cc43e2b2aef882c867fc3c84a8d9df3d9f Mon Sep 17 00:00:00 2001 From: sheidkamp Date: Thu, 14 Nov 2024 13:21:42 -0500 Subject: [PATCH 2/5] Create no-external-links.yaml --- changelog/v0.36.2/no-external-links.yaml | 6 ++++++ 1 file changed, 6 insertions(+) create mode 100644 changelog/v0.36.2/no-external-links.yaml diff --git a/changelog/v0.36.2/no-external-links.yaml b/changelog/v0.36.2/no-external-links.yaml new file mode 100644 index 000000000..984f45e22 --- /dev/null +++ b/changelog/v0.36.2/no-external-links.yaml @@ -0,0 +1,6 @@ +changelog: +- type: FIX + issueLink: https://github.com/solo-io/solo-projects/issues/6768 + resolvesIssue: false + description: >- + Update protobuf processing to no longer render links to locally hosted external API docs, as they are being removed. From 415c33bf096d70b195bd3f7a26420681b2ea7f3c Mon Sep 17 00:00:00 2001 From: sheidkamp Date: Thu, 14 Nov 2024 15:19:34 -0500 Subject: [PATCH 3/5] make link changes configurable --- .../docgen/funcs/template_funcs.go | 8 +++++--- pkg/code-generator/docgen/options/options.go | 17 +++++++++++++++-- 2 files changed, 20 insertions(+), 5 deletions(-) diff --git a/pkg/code-generator/docgen/funcs/template_funcs.go b/pkg/code-generator/docgen/funcs/template_funcs.go index 1c566e6d9..ea23d477c 100644 --- a/pkg/code-generator/docgen/funcs/template_funcs.go +++ b/pkg/code-generator/docgen/funcs/template_funcs.go @@ -319,9 +319,11 @@ func linkForField(project *model.Project, docsOptions *options.DocsOptions) func //return "", errors.Errorf("failed to get generated file path for proto %v in list %v", file.GetName(), project.Request.FileToGenerate) } - // Don't link to external apis docs, as they will be deleted - if strings.HasPrefix(linkedFile, "github.com/solo-io/gloo/projects/gloo/api/external") { - return typeName, nil + // Skip links for packages that are configured to be skipped + for _, pkg := range docsOptions.RenderOptions.GetSkipLinksForPackages() { + if strings.HasPrefix(linkedFile, pkg) { + return typeName, nil + } } linkedFile = relativeFilename(forFile.GetName(), linkedFile) diff --git a/pkg/code-generator/docgen/options/options.go b/pkg/code-generator/docgen/options/options.go index 27eda005c..3843bcafe 100644 --- a/pkg/code-generator/docgen/options/options.go +++ b/pkg/code-generator/docgen/options/options.go @@ -21,8 +21,21 @@ type HugoOptions struct { } type DocsOptions struct { - Output DocsOutput - HugoOptions *HugoOptions + Output DocsOutput + HugoOptions *HugoOptions + RenderOptions *RenderOptions +} + +// RenderOptions provides options for rendering documentation +type RenderOptions struct { + SkipLinksForPackages []string // when rendering markdown, do not attempt to link to these packages or their subpackages +} + +func (o *RenderOptions) GetSkipLinksForPackages() []string { + if o == nil { + return nil + } + return o.SkipLinksForPackages } const ( From 74c6e05d5a8555ee153aabd55c283edbe5bd1e51 Mon Sep 17 00:00:00 2001 From: sheidkamp Date: Thu, 14 Nov 2024 16:43:22 -0500 Subject: [PATCH 4/5] rename and add example --- pkg/code-generator/docgen/funcs/template_funcs.go | 2 +- pkg/code-generator/docgen/options/options.go | 8 +++++--- 2 files changed, 6 insertions(+), 4 deletions(-) diff --git a/pkg/code-generator/docgen/funcs/template_funcs.go b/pkg/code-generator/docgen/funcs/template_funcs.go index ea23d477c..847f2cc99 100644 --- a/pkg/code-generator/docgen/funcs/template_funcs.go +++ b/pkg/code-generator/docgen/funcs/template_funcs.go @@ -320,7 +320,7 @@ func linkForField(project *model.Project, docsOptions *options.DocsOptions) func } // Skip links for packages that are configured to be skipped - for _, pkg := range docsOptions.RenderOptions.GetSkipLinksForPackages() { + for _, pkg := range docsOptions.RenderOptions.GetSkipLinksForPathPrefixes() { if strings.HasPrefix(linkedFile, pkg) { return typeName, nil } diff --git a/pkg/code-generator/docgen/options/options.go b/pkg/code-generator/docgen/options/options.go index 3843bcafe..e220622d1 100644 --- a/pkg/code-generator/docgen/options/options.go +++ b/pkg/code-generator/docgen/options/options.go @@ -28,14 +28,16 @@ type DocsOptions struct { // RenderOptions provides options for rendering documentation type RenderOptions struct { - SkipLinksForPackages []string // when rendering markdown, do not attempt to link to these packages or their subpackages + // SkipLinksForPathPrefixes is a list of file path prefixes foofr APIs to which we should not be attempting to link + // For example: "github.com/solo-io/gloo/projects/gloo/api/external" + SkipLinksForPathPrefixes []string } -func (o *RenderOptions) GetSkipLinksForPackages() []string { +func (o *RenderOptions) GetSkipLinksForPathPrefixes() []string { if o == nil { return nil } - return o.SkipLinksForPackages + return o.SkipLinksForPathPrefixes } const ( From 0c728acac7ca65b5bb3cf8e44514d7e90c0ab201 Mon Sep 17 00:00:00 2001 From: sheidkamp Date: Thu, 14 Nov 2024 16:43:42 -0500 Subject: [PATCH 5/5] Update options.go --- pkg/code-generator/docgen/options/options.go | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pkg/code-generator/docgen/options/options.go b/pkg/code-generator/docgen/options/options.go index e220622d1..29ef61941 100644 --- a/pkg/code-generator/docgen/options/options.go +++ b/pkg/code-generator/docgen/options/options.go @@ -28,7 +28,7 @@ type DocsOptions struct { // RenderOptions provides options for rendering documentation type RenderOptions struct { - // SkipLinksForPathPrefixes is a list of file path prefixes foofr APIs to which we should not be attempting to link + // SkipLinksForPathPrefixes is a list of file path prefixes of APIs to which we should not be attempting to link // For example: "github.com/solo-io/gloo/projects/gloo/api/external" SkipLinksForPathPrefixes []string }