Merge branch 'main' into audit

docs/administration/email-setup.md

@@ -86,6 +86,21 @@ PROTOCOL       = smtps
 Note that you'll need to create and use an [App password](https://support.google.com/accounts/answer/185833?hl=en) by enabling 2FA on your Google
 account. You won't be able to use your Google account password directly.
 
+An app password is the only option: Google
+[turned off access for apps that sign in with a password alone](https://workspaceupdates.googleblog.com/2023/09/winding-down-google-sync-and-less-secure-apps-support.html)
+in 2024 and asks applications to use OAuth instead, which Gitea's mailer does
+not implement — it authenticates with `CRAM-MD5`, `PLAIN` or `LOGIN`.
+
+Two things to keep in mind:
+
+- app passwords require 2-step verification on the account, and a Google
+  Workspace administrator can switch them off for the whole domain. If they are
+  not available, send through the
+  [Workspace SMTP relay service](https://support.google.com/a/answer/2956491)
+  or through another mail provider.
+- port `587` works as well, with `SMTP_PORT = 587` and
+  `PROTOCOL = smtp+starttls`.
+
 ### ProtonMail
 
 This feature is currently only available for select Proton for Business customers and those with Visionary and Family plans with custom domain addresses. See [ProtonMail's SMTP documentation](https://proton.me/support/smtp-submission) for more information. This limitation can be circumvented by using the ProtonMail Bridge application.

sites/docs/src/config/api.ts

@@ -27,6 +27,11 @@ interface Operation {
   operationId?: string;
 }
 
+interface Schema {
+  title?: string;
+  description?: string;
+}
+
 interface SwaggerDocument {
   openapi?: string;
   basePath?: string;
@@ -34,6 +39,7 @@ interface SwaggerDocument {
   schemes?: string[];
   tags?: { name: string; description?: string }[];
   paths?: Record<string, Record<string, Operation | unknown>>;
+  components?: { schemas?: Record<string, Schema> };
 }
 
 const httpMethods = ['get', 'put', 'post', 'delete', 'options', 'head', 'patch'];
@@ -95,6 +101,7 @@ function normalizeSchema(source: string, name: string): string {
   hyphenateOperationIds(document);
 
   describeTags(document);
+  nameSchemas(document);
 
   mkdirSync(cacheDir, { recursive: true });
   const target = path.join(cacheDir, name);
@@ -123,6 +130,32 @@ function describeTags(document: SwaggerDocument): void {
   document.tags = [...described.values()];
 }
 
+/**
+ * Titles the named schemas of an openapi 3.0 document with their own name.
+ *
+ * starlight-openapi dereferences every `$ref`, so a field of type
+ * `ReviewStateType` is rendered as the bare string enum it points at and the
+ * name of the type is nowhere on the page: searching the reference for a type
+ * name found in an sdk or in an error message turns up nothing (gitea/docs#258).
+ * The plugin renders `title` next to the type of a field, so setting it brings
+ * the name back, next to the allowed values.
+ *
+ * Swagger 2.0 documents are left alone, they are rendered with the name of the
+ * definition already.
+ */
+function nameSchemas(document: SwaggerDocument): void {
+  for (const [name, schema] of Object.entries(document.components?.schemas ?? {})) {
+    if (!schema || typeof schema !== 'object') continue;
+    if (!schema.title) schema.title = name;
+    // the go doc comments start with the name of the type, which would read
+    // "ChangeFilesOptions — ChangeFilesOptions options for ..." once the title
+    // is rendered in front of the description
+    if (schema.description?.startsWith(`${name} `)) {
+      schema.description = schema.description.slice(name.length + 1);
+    }
+  }
+}
+
 /**
  * One starlight-openapi schema per documented api version, each mounted at the
  * route of its version: `/api/` for the latest release, `/api/1.26/` and