fix(docs): section headers are not valid markdown (#7075)

Co-authored-by: wingbot <[email protected]> Co-authored-by: monada-bot[bot] <[email protected]>
winglang · Sep 4, 2024 · 57b80a2 · 57b80a2
1 parent cc77a45
commit 57b80a2
Show file tree

Hide file tree

Showing 3 changed files with 87 additions and 65 deletions.
diff --git a/packages/@winglang/wingc/src/generate_docs.rs b/packages/@winglang/wingc/src/generate_docs.rs
@@ -156,7 +156,7 @@ fn generate_docs_helper(types: &Types, project_dir: &Utf8Path) -> Result<String,
 		SymbolEnvOrNamespace::Error(diag) => panic!("Error in root env: {}", diag),
 	};
 
-	docs.push_str("<h2>API Reference</h2>\n\n");
+	docs.push_str("## API Reference\n\n");
 
 	let mut public_types = vec![];
 	let namespaces = find_documentable_namespaces_recursive(&ns);
@@ -220,7 +220,7 @@ fn simplified_fqn(typ: &TypeRef) -> String {
 }
 
 fn print_table_of_contents(types: &[TypeRef], docs: &mut String) {
-	docs.push_str("<h3>Table of Contents</h3>\n\n");
+	docs.push_str("### Table of Contents\n\n");
 
 	let mut classes = vec![];
 	let mut interfaces = vec![];
@@ -287,19 +287,21 @@ fn print_table_of_contents(types: &[TypeRef], docs: &mut String) {
 fn print_classes(types: &[TypeRef], docs: &mut String) {
 	for typ in types {
 		if let Type::Class(ref class) = **typ {
-			docs.push_str("<h3 id=\"");
-			docs.push_str(&typ.fqn().expect("Type has no FQN"));
-			docs.push_str("\">");
+			docs.push_str("### ");
 			docs.push_str(&simplified_fqn(typ));
 			docs.push_str(" (");
 			docs.push_str(&class.phase.to_string());
-			docs.push_str(" class)</h3>\n\n");
+			docs.push_str(" class) <a class=\"wing-docs-anchor\" id=\"");
+			docs.push_str(&typ.fqn().expect("Type has no FQN"));
+			docs.push_str("\"></a>\n\n");
 
 			let docstring = class.docs.render();
 			if !docstring.is_empty() {
 				docs.push_str(&docstring);
-				docs.push_str("\n\n");
+			} else {
+				docs.push_str("*No description*");
 			}
+			docs.push_str("\n\n");
 
 			print_constructors(docs, class);
 			print_properties(docs, class);
@@ -311,17 +313,19 @@ fn print_classes(types: &[TypeRef], docs: &mut String) {
 fn print_interfaces(types: &[TypeRef], docs: &mut String) {
 	for typ in types {
 		if let Type::Interface(ref interface) = **typ {
-			docs.push_str("<h3 id=\"");
-			docs.push_str(&typ.fqn().expect("Type has no FQN"));
-			docs.push_str("\">");
+			docs.push_str("### ");
 			docs.push_str(&simplified_fqn(typ));
-			docs.push_str(" (interface)</h3>\n\n");
+			docs.push_str(" (interface) <a class=\"wing-docs-anchor\" id=\"");
+			docs.push_str(&typ.fqn().expect("Type has no FQN"));
+			docs.push_str("\"></a>\n\n");
 
 			let docstring = interface.docs.render();
 			if !docstring.is_empty() {
 				docs.push_str(&docstring);
-				docs.push_str("\n\n");
+			} else {
+				docs.push_str("*No description*");
 			}
+			docs.push_str("\n\n");
 
 			print_properties(docs, interface);
 			print_methods(docs, interface);
@@ -332,17 +336,19 @@ fn print_interfaces(types: &[TypeRef], docs: &mut String) {
 fn print_structs(types: &[TypeRef], docs: &mut String) {
 	for typ in types {
 		if let Type::Struct(ref struct_) = **typ {
-			docs.push_str("<h3 id=\"");
-			docs.push_str(&typ.fqn().expect("Type has no FQN"));
-			docs.push_str("\">");
+			docs.push_str("### ");
 			docs.push_str(&simplified_fqn(typ));
-			docs.push_str(" (struct)</h3>\n\n");
+			docs.push_str(" (struct) <a class=\"wing-docs-anchor\" id=\"");
+			docs.push_str(&typ.fqn().expect("Type has no FQN"));
+			docs.push_str("\"></a>\n\n");
 
 			let docstring = struct_.docs.render();
 			if !docstring.is_empty() {
 				docs.push_str(&docstring);
-				docs.push_str("\n\n");
+			} else {
+				docs.push_str("*No description*");
 			}
+			docs.push_str("\n\n");
 
 			print_properties(docs, struct_);
 		}
@@ -352,19 +358,21 @@ fn print_structs(types: &[TypeRef], docs: &mut String) {
 fn print_enums(types: &[TypeRef], docs: &mut String) {
 	for typ in types {
 		if let Type::Enum(ref enum_) = **typ {
-			docs.push_str("<h3 id=\"");
-			docs.push_str(&typ.fqn().expect("Type has no FQN"));
-			docs.push_str("\">");
+			docs.push_str("### ");
 			docs.push_str(&simplified_fqn(typ));
-			docs.push_str(" (enum)</h3>\n\n");
+			docs.push_str(" (enum) <a class=\"wing-docs-anchor\" id=\"");
+			docs.push_str(&typ.fqn().expect("Type has no FQN"));
+			docs.push_str("\"></a>\n\n");
 
 			let docstring = enum_.docs.render();
 			if !docstring.is_empty() {
 				docs.push_str(&docstring);
-				docs.push_str("\n\n");
+			} else {
+				docs.push_str("*No description*");
 			}
+			docs.push_str("\n\n");
 
-			docs.push_str("<h4>Values</h4>\n\n");
+			docs.push_str("#### Values\n\n");
 			docs.push_str("| **Name** | **Description** |\n");
 			docs.push_str("| --- | --- |\n");
 			for (name, description) in enum_.values.iter() {
@@ -385,7 +393,7 @@ fn print_enums(types: &[TypeRef], docs: &mut String) {
 }
 
 fn print_constructors(docs: &mut String, class: &impl ClassLike) {
-	docs.push_str("<h4>Constructor</h4>\n\n");
+	docs.push_str("#### Constructor\n\n");
 
 	let mut constructors = class.constructors(true).collect::<Vec<_>>();
 	constructors.retain(|(_, constructor_info)| constructor_info.access == AccessModifier::Public);
@@ -395,7 +403,7 @@ fn print_constructors(docs: &mut String, class: &impl ClassLike) {
 	if constructors.is_empty() {
 		docs.push_str("*No constructor*\n");
 	} else {
-		docs.push_str("<pre>\n");
+		docs.push_str("```\n");
 		for (_, constructor_info) in constructors {
 			let sig = constructor_info
 				.type_
@@ -404,14 +412,14 @@ fn print_constructors(docs: &mut String, class: &impl ClassLike) {
 			print_signature(&VariableKind::InstanceMember, "new", sig, docs);
 			docs.push_str("\n");
 		}
-		docs.push_str("</pre>\n");
+		docs.push_str("```\n");
 	}
 
 	docs.push_str("\n");
 }
 
 fn print_properties(docs: &mut String, class: &impl ClassLike) {
-	docs.push_str("<h4>Properties</h4>\n\n");
+	docs.push_str("#### Properties\n\n");
 
 	let mut fields = class.fields(true).collect::<Vec<_>>();
 	fields.retain(|(_, field_info)| field_info.access == AccessModifier::Public);
@@ -441,7 +449,7 @@ fn print_properties(docs: &mut String, class: &impl ClassLike) {
 }
 
 fn print_methods(docs: &mut String, class: &impl ClassLike) {
-	docs.push_str("<h4>Methods</h4>\n\n");
+	docs.push_str("#### Methods\n\n");
 
 	let mut methods = class.methods(true).collect::<Vec<_>>();
 	methods.retain(|(_, method_info)| method_info.access == AccessModifier::Public);

diff --git a/packages/@winglibs/testfixture/API.md b/packages/@winglibs/testfixture/API.md
@@ -1,6 +1,6 @@
-<h2>API Reference</h2>
+## API Reference
 
-<h3>Table of Contents</h3>
+### Table of Contents
 
 - **Classes**
   - <a href="#@winglibs/testfixture.PublicClass">PublicClass</a>
@@ -14,39 +14,43 @@
 - **Enums**
   - <a href="#@winglibs/testfixture.FavoriteNumbers">FavoriteNumbers</a>
 
-<h3 id="@winglibs/testfixture.PublicClass">PublicClass (preflight class)</h3>
+### PublicClass (preflight class) <a class="wing-docs-anchor" id="@winglibs/testfixture.PublicClass"></a>
 
-<h4>Constructor</h4>
+*No description*
 
-<pre>
+#### Constructor
+
+```
 new(): PublicClass
-</pre>
+```
 
-<h4>Properties</h4>
+#### Properties
 
 | **Name** | **Type** | **Description** |
 | --- | --- | --- |
 | <code>publicField</code> | <code>num</code> | *No description* |
 
-<h4>Methods</h4>
+#### Methods
 
 | **Signature** | **Description** |
 | --- | --- |
 | <code>publicMethod(): void</code> | *No description* |
 
-<h3 id="@winglibs/testfixture.Store">Store (preflight class)</h3>
+### Store (preflight class) <a class="wing-docs-anchor" id="@winglibs/testfixture.Store"></a>
+
+*No description*
 
-<h4>Constructor</h4>
+#### Constructor
 
-<pre>
+```
 new(options: StoreOptions?): Store
-</pre>
+```
 
-<h4>Properties</h4>
+#### Properties
 
 *No properties*
 
-<h4>Methods</h4>
+#### Methods
 
 | **Signature** | **Description** |
 | --- | --- |
@@ -55,52 +59,62 @@ new(options: StoreOptions?): Store
 | <code>onSet(handler: inflight (str): void): void</code> | *No description* |
 | <code>inflight set(message: str): void</code> | *No description* |
 
-<h3 id="@winglibs/testfixture.subdir.Util">subdir.Util (preflight class)</h3>
+### subdir.Util (preflight class) <a class="wing-docs-anchor" id="@winglibs/testfixture.subdir.Util"></a>
 
-<h4>Constructor</h4>
+*No description*
 
-<pre>
+#### Constructor
+
+```
 new(): Util
-</pre>
+```
 
-<h4>Properties</h4>
+#### Properties
 
 *No properties*
 
-<h4>Methods</h4>
+#### Methods
 
 | **Signature** | **Description** |
 | --- | --- |
 | <code>static inflight double(msg: str): str</code> | *No description* |
 | <code>static inflight makeKeyInflight(name: str): str</code> | *No description* |
 
-<h3 id="@winglibs/testfixture.PublicInterface">PublicInterface (interface)</h3>
+### PublicInterface (interface) <a class="wing-docs-anchor" id="@winglibs/testfixture.PublicInterface"></a>
+
+*No description*
 
-<h4>Properties</h4>
+#### Properties
 
 *No properties*
 
-<h4>Methods</h4>
+#### Methods
 
 *No methods*
 
-<h3 id="@winglibs/testfixture.PublicStruct">PublicStruct (struct)</h3>
+### PublicStruct (struct) <a class="wing-docs-anchor" id="@winglibs/testfixture.PublicStruct"></a>
 
-<h4>Properties</h4>
+*No description*
+
+#### Properties
 
 *No properties*
 
-<h3 id="@winglibs/testfixture.StoreOptions">StoreOptions (struct)</h3>
+### StoreOptions (struct) <a class="wing-docs-anchor" id="@winglibs/testfixture.StoreOptions"></a>
+
+*No description*
 
-<h4>Properties</h4>
+#### Properties
 
 | **Name** | **Type** | **Description** |
 | --- | --- | --- |
 | <code>name</code> | <code>str?</code> | *No description* |
 
-<h3 id="@winglibs/testfixture.FavoriteNumbers">FavoriteNumbers (enum)</h3>
+### FavoriteNumbers (enum) <a class="wing-docs-anchor" id="@winglibs/testfixture.FavoriteNumbers"></a>
+
+*No description*
 
-<h4>Values</h4>
+#### Values
 
 | **Name** | **Description** |
 | --- | --- |

diff --git a/packages/winglang/fixtures/valid1/API.md b/packages/winglang/fixtures/valid1/API.md
@@ -1,25 +1,25 @@
-<h2>API Reference</h2>
+## API Reference
 
-<h3>Table of Contents</h3>
+### Table of Contents
 
 - **Classes**
   - <a href="#valid1.Foo">Foo</a>
 
-<h3 id="valid1.Foo">Foo (preflight class)</h3>
+### Foo (preflight class) <a class="wing-docs-anchor" id="valid1.Foo"></a>
 
 A test class
 
-<h4>Constructor</h4>
+#### Constructor
 
-<pre>
+```
 new(): Foo
-</pre>
+```
 
-<h4>Properties</h4>
+#### Properties
 
 *No properties*
 
-<h4>Methods</h4>
+#### Methods
 
 *No methods*