From 4f0adc46915ad8517bc4c1c347a5b7c86519847d Mon Sep 17 00:00:00 2001
From: Edward Thomson <ethomson@stacklok.com>
Date: Mon, 1 Jul 2024 11:39:08 +0100
Subject: [PATCH] Emit well-typed MDX in protocol documentation

The generated protocol documentation has a few issues:

1. It creates its own anchors for linking things like request, response,
   and scalar types. However, docusaurus's link checker doesn't know
   about these generated anchors and emits false positives. Instead,
   create React components to generate the titles and anchors, so that
   we can tell docusaurus about these anchors.
2. The links to scalar types assume that we know about all of them. The
   google.protobuf.* types are not documented by us. Create a TypeLink
   component that understands this difference and links to the protobuf
   docs for things like Timestamp.
---
 docs/proto_template.tmpl | 62 +++++++++++++++++++++++++++++++---------
 1 file changed, 48 insertions(+), 14 deletions(-)

diff --git a/docs/proto_template.tmpl b/docs/proto_template.tmpl
index b93b521712..02be96d64b 100644
--- a/docs/proto_template.tmpl
+++ b/docs/proto_template.tmpl
@@ -2,23 +2,57 @@
 sidebar_position: 60
 toc_max_heading_level: 4
 ---
+
+import useBrokenLinks from '@docusaurus/useBrokenLinks';
+
+export const File = ({ children, id }) => {
+  useBrokenLinks().collectAnchor(id);
+  return <h2 id={id} name={id}>{children}</h2>;
+}
+export const Service = ({ children, id }) => {
+  useBrokenLinks().collectAnchor(id);
+  return <h4 id={id} name={id}>{children}</h4>;
+}
+export const Message = ({ children, id }) => {
+  useBrokenLinks().collectAnchor(id);
+  return <h4 id={id} name={id}>{children}</h4>;
+}
+export const Extension = ({ children, id }) => {
+  useBrokenLinks().collectAnchor(id);
+  return <h3 id={id} name={id}>{children}</h3>;
+}
+export const Enum = ({ children, id }) => {
+  useBrokenLinks().collectAnchor(id);
+  return <h3 id={id} name={id}>{children}</h3>;
+}
+export const ProtoType = ({ children, id }) => {
+  useBrokenLinks().collectAnchor(id);
+  return <a id={id} name={id}>{children}</a>;
+}
+export const TypeLink = ({ children, type }) => {
+  let link = type.startsWith('google-protobuf-') ?
+    `https://protobuf.dev/reference/protobuf/google.protobuf/#${type.replace('google-protobuf-', '')}` :
+    `#${type}`;
+  return <a href={link}>{children}</a>;
+}
+
+
 # Protocol documentation
-<a name="top"></a>
+<a id="top"></a>
 
 {{range .Files}}
 {{$file_name := .Name}}
-<a name="{{.Name | anchor}}"></a>
-<p align="right"><a href="#top">Top</a></p>
 
-## {{.Name}}
+<File id="{{.Name | anchor}}">{{.Name}}</File>
+
 {{.Description}}
 
 {{- if .Services}}
 ### Services
 {{range .Services}}
-<a name="{{.FullName | anchor}}"></a>
 
-#### {{.Name}}
+<Service id="{{.FullName | anchor}}">{{.Name}}</Service>
+
 {{.Description}}
 
 | Method Name | Request Type | Response Type | Description |
@@ -32,16 +66,16 @@ toc_max_heading_level: 4
 {{- if .Messages}}
 ### Messages
 {{range .Messages}}
-<a name="{{.FullName | anchor}}"></a>
 
-#### {{.LongName}}
+<Message id="{{.FullName | anchor}}">{{.LongName}}</Message>
+
 {{.Description}}
 
 {{if .HasFields}}
 | Field | Type | Label | Description |
 | ----- | ---- | ----- | ----------- |
 {{range .Fields -}}
-  | {{.Name}} | [{{.LongType}}](#{{.FullType | anchor}}) | {{.Label}} | {{if (index .Options "deprecated"|default false)}}**Deprecated.** {{end}}{{nobr .Description}}{{if .DefaultValue}} Default: {{.DefaultValue}}{{end}} |
+  | {{.Name}} | <TypeLink type="{{.FullType | anchor}}">{{.LongType}}</TypeLink> | {{.Label}} | {{if (index .Options "deprecated"|default false)}}**Deprecated.** {{end}}{{nobr .Description}}{{if .DefaultValue}} Default: {{.DefaultValue}}{{end}} |
 {{end}}
 {{end}}
 {{- end -}}
@@ -56,9 +90,9 @@ toc_max_heading_level: 4
 {{end}}
 
 {{range .Enums}}
-<a name="{{.FullName | anchor}}"></a>
 
-### {{.LongName}}
+<Enum id="{{.FullName | anchor}}">{{.LongName}}</Enum>
+
 {{.Description}}
 
 | Name | Number | Description |
@@ -69,9 +103,9 @@ toc_max_heading_level: 4
 {{end}}
 
 {{if .HasExtensions}}
-<a name="{{$file_name | anchor}}-extensions"></a>
 
-### File-level Extensions
+<Extension id="{{$file_name | anchor}}-extensions">File-level Extensions</Extension>
+
 | Extension | Type | Base | Number | Description |
 | --------- | ---- | ---- | ------ | ----------- |
 {{range .Extensions -}}
@@ -86,5 +120,5 @@ toc_max_heading_level: 4
 | .proto Type | Notes | C++ | Java | Python | Go | C# | PHP | Ruby |
 | ----------- | ----- | --- | ---- | ------ | -- | -- | --- | ---- |
 {{range .Scalars -}}
-  | <a name="{{.ProtoType | anchor}}" /> {{.ProtoType}} | {{.Notes}} | {{.CppType}} | {{.JavaType}} | {{.PythonType}} | {{.GoType}} | {{.CSharp}} | {{.PhpType}} | {{.RubyType}} |
+  | <ProtoType id="{{.ProtoType | anchor}}">{{.ProtoType}}</ProtoType> | {{.Notes}} | {{.CppType}} | {{.JavaType}} | {{.PythonType}} | {{.GoType}} | {{.CSharp}} | {{.PhpType}} | {{.RubyType}} |
 {{end}}