chore: generate a documentation index for REST API docs in docs/api

Signed-off-by: NotAShelf <raf@notashelf.dev>
Change-Id: Ia8426a63a50d07a6cec2b104951d58eb6a6a6964

xtask/src/docs.rs

@@ -95,8 +95,45 @@ pub fn run() {
     files_written += 1;
   }
 
+  // Generate docs/api.md index
+  let index_path = std::path::Path::new("docs/api.md");
+  let mut index = String::new();
+  index.push_str("# API Documentation\n\n");
+  index.push_str(
+    "This is the index of all generated REST API documentation for \
+     Pinakes.\n\n",
+  );
+  index.push_str(
+    "Documentation is generated from OpenAPI annotations via `cargo xtask \
+     docs`\n",
+  );
+  index.push_str("(or `just docs`). Do not edit generated files by hand.\n\n");
+  index.push_str("## Reference\n\n");
+  index.push_str(
+    "- [openapi.json](api/openapi.json) - Full OpenAPI 3.0 specification\n\n",
+  );
+  index.push_str("## Endpoints by Tag\n\n");
+  for tag_name in tag_ops.keys() {
+    let file_name = format!("{}.md", tag_name.replace('/', "_"));
+    let description = tag_descriptions.get(tag_name).map_or("", String::as_str);
+    if description.is_empty() {
+      writeln!(index, "- [{}](api/{file_name})", title_case(tag_name))
+        .expect("write to String");
+    } else {
+      writeln!(
+        index,
+        "- [{}](api/{file_name}) - {description}",
+        title_case(tag_name)
+      )
+      .expect("write to String");
+    }
+  }
+  std::fs::write(index_path, &index).expect("write docs/api.md");
+  println!("Written docs/api.md");
+
   println!(
-    "Done: wrote docs/api/openapi.json and {files_written} markdown files."
+    "Done: wrote docs/api/openapi.json, docs/api.md, and {files_written} \
+     markdown files."
   );
 }