Use ruamel.yaml to format the OpenAPI spec (#892)

Stainless ends up reformatting the YAML when we paste it in the Studio.
We cannot have that happen if we are going to ever partially automate
stainless config updates.

Try ruamel.yaml, specifically `block_seq_indent` to avoid that.

docs/openapi_generator/generate.py

@@ -14,7 +14,7 @@ from datetime import datetime
 from pathlib import Path
 
 import fire
-import yaml
+import ruamel.yaml as yaml
 
 from llama_models import schema_utils
 
@@ -61,7 +61,19 @@ def main(output_dir: str):
     )
 
     with open(output_dir / "llama-stack-spec.yaml", "w", encoding="utf-8") as fp:
-        yaml.dump(spec.get_json(), fp, allow_unicode=True)
+        y = yaml.YAML()
+        y.default_flow_style = False
+        y.block_seq_indent = 2
+        y.map_indent = 2
+        y.sequence_indent = 4
+        y.sequence_dash_offset = 2
+        y.width = 80
+        y.allow_unicode = True
+        y.explicit_start = True
+        y.dump(
+            spec.get_json(),
+            fp,
+        )
 
     with open(output_dir / "llama-stack-spec.html", "w") as fp:
         spec.write_html(fp, pretty_print=True)

docs/openapi_generator/pyopenapi/generator.py

@@ -403,14 +403,16 @@ class Generator:
         self.responses = {}
 
     def _build_type_tag(self, ref: str, schema: Schema) -> Tag:
-        definition = f'<SchemaDefinition schemaRef="#/components/schemas/{ref}" />'
+        # Don't include schema definition in the tag description because for one,
+        # it is not very valuable and for another, it causes string formatting
+        # discrepancies via the Stainless Studio.
+        #
+        # definition = f'<SchemaDefinition schemaRef="#/components/schemas/{ref}" />'
         title = typing.cast(str, schema.get("title"))
         description = typing.cast(str, schema.get("description"))
         return Tag(
             name=ref,
-            description="\n\n".join(
-                s for s in (title, description, definition) if s is not None
-            ),
+            description="\n\n".join(s for s in (title, description) if s is not None),
         )
 
     def _build_extra_tag_groups(