Convert generated doc links to reStructuredText

Author: razor-x

codegen/lib/layouts/resources.ts

@@ -6,6 +6,7 @@ import type { Blueprint, Property, Resource } from '@seamapi/blueprint'
 import { pascalCase, snakeCase } from 'change-case'
 
 import { convertCustomResourceName } from '../custom-resource-name-conversions.js'
+import { formatPythonDoc } from '../python-docstring.js'
 import { mapPropertyToPythonType } from '../python-type.js'
 
 // Python hard keywords cannot be used as identifiers. When a property name
@@ -65,25 +66,22 @@ export interface ResourceLayoutContext {
   }>
 }
 
-const cleanDoc = (value: string): string =>
-  value.trim().replaceAll('"""', '\\"\\"\\"')
-
 const createResourceDocstring = (
   description: string,
   isDeprecated: boolean,
   deprecationMessage: string,
   properties: Property[],
 ): string => {
-  const lines = [cleanDoc(description)]
+  const lines = [formatPythonDoc(description)]
   for (const property of properties) {
     const deprecated = property.isDeprecated
-      ? `Deprecated${property.deprecationMessage === '' ? '.' : `: ${cleanDoc(property.deprecationMessage)}`}`
+      ? `Deprecated${property.deprecationMessage === '' ? '.' : `: ${formatPythonDoc(property.deprecationMessage)}`}`
       : ''
     lines.push(
       '',
       `:ivar ${toSafeIdentifier(property.name)}: ${[
         deprecated,
-        cleanDoc(property.description),
+        formatPythonDoc(property.description),
       ]
         .filter(Boolean)
         .join(' ')}`,
@@ -94,7 +92,7 @@ const createResourceDocstring = (
     lines.push(
       '',
       '.. deprecated::',
-      `   ${cleanDoc(deprecationMessage) || 'This resource is deprecated.'}`,
+      `   ${formatPythonDoc(deprecationMessage) || 'This resource is deprecated.'}`,
     )
   }
   return lines

codegen/lib/layouts/route.ts

@@ -8,6 +8,7 @@ import {
   type ClassModel,
   sortClassMethodParameters,
 } from '../class-model.js'
+import { formatPythonDoc } from '../python-docstring.js'
 
 export interface MethodLayoutContext {
   name: string
@@ -57,23 +58,20 @@ export interface RouteLayoutContext {
 const waitForActionAttemptParameter =
   'wait_for_action_attempt: Optional[Union[bool, Dict[str, float]]] = None'
 
-const cleanDoc = (value: string): string =>
-  value.trim().replaceAll('"""', '\\"\\"\\"')
-
 const indentDoc = (value: string, spaces: number): string =>
   value.replaceAll('\n', `\n${' '.repeat(spaces)}`)
 
 const methodDocstring = (
   method: ClassMethod,
   sortedParameters: ClassMethod['parameters'],
 ): string => {
-  const lines = [cleanDoc(method.description)]
+  const lines = [formatPythonDoc(method.description)]
 
   for (const parameter of sortedParameters) {
     const deprecated = parameter.isDeprecated
-      ? `Deprecated${parameter.deprecationMessage === '' ? '.' : `: ${cleanDoc(parameter.deprecationMessage)}`}`
+      ? `Deprecated${parameter.deprecationMessage === '' ? '.' : `: ${formatPythonDoc(parameter.deprecationMessage)}`}`
       : ''
-    const description = cleanDoc(parameter.description)
+    const description = formatPythonDoc(parameter.description)
     lines.push(
       '',
       `:param ${parameter.name}: ${[deprecated, description].filter(Boolean).join(' ')}`,
@@ -92,7 +90,7 @@ const methodDocstring = (
   if (method.returnResource !== 'None') {
     lines.push(
       '',
-      `:returns: ${cleanDoc(method.responseDescription)}`,
+      `:returns: ${formatPythonDoc(method.responseDescription)}`,
       `:rtype: ${method.returnResource}`,
     )
   }
@@ -101,7 +99,7 @@ const methodDocstring = (
     lines.push(
       '',
       '.. deprecated::',
-      `   ${cleanDoc(method.deprecationMessage) || 'This method is deprecated.'}`,
+      `   ${formatPythonDoc(method.deprecationMessage) || 'This method is deprecated.'}`,
     )
   }
 

codegen/lib/python-docstring.ts

@@ -0,0 +1,9 @@
+// Blueprint descriptions use Markdown, while the generated Python docstrings
+// use Sphinx/reStructuredText fields. Normalize the Markdown constructs that
+// would otherwise be displayed literally (or interpreted as invalid roles).
+export const formatPythonDoc = (value: string): string =>
+  value
+    .trim()
+    .replaceAll('"""', '\\"\\"\\"')
+    .replaceAll(/(?<!`)`([^`\n]+)`(?!`)/g, '``$1``')
+    .replaceAll(/\[([^\]]+)]\(([^)]+)\)/g, '`$1 <$2>`_')

seam/resources/access_code.py

@@ -5,15 +5,15 @@
 
 @dataclass
 class AccessCode:
-    """Represents a smart lock [access code](https://docs.seam.co/low-level-apis/smart-locks/access-codes).
+    """Represents a smart lock `access code <https://docs.seam.co/low-level-apis/smart-locks/access-codes>`_.
 
     An access code is a code used for a keypad or pinpad device. Unlike physical keys, which can easily be lost or duplicated, PIN codes can be customized, tracked, and altered on the fly. Using the Seam Access Code API, you can easily generate access codes on the hundreds of door lock models with which we integrate.
 
-    Seam supports programming two types of access codes: [ongoing](https://docs.seam.co/low-level-apis/smart-locks/access-codes#ongoing-access-codes) and [time-bound](https://docs.seam.co/low-level-apis/smart-locks/access-codes#time-bound-access-codes). To differentiate between the two, refer to the `type` property of the access code. Ongoing codes display as `ongoing`, whereas time-bound codes are labeled `time_bound`. An ongoing access code is active, until it has been removed from the device. To specify an ongoing access code, leave both `starts_at` and `ends_at` empty. A time-bound access code will be programmed at the `starts_at` time and removed at the `ends_at` time.
+    Seam supports programming two types of access codes: `ongoing <https://docs.seam.co/low-level-apis/smart-locks/access-codes#ongoing-access-codes>`_ and `time-bound <https://docs.seam.co/low-level-apis/smart-locks/access-codes#time-bound-access-codes>`_. To differentiate between the two, refer to the ``type`` property of the access code. Ongoing codes display as ``ongoing``, whereas time-bound codes are labeled ``time_bound``. An ongoing access code is active, until it has been removed from the device. To specify an ongoing access code, leave both ``starts_at`` and ``ends_at`` empty. A time-bound access code will be programmed at the ``starts_at`` time and removed at the ``ends_at`` time.
 
-    In addition, for certain devices, Seam also supports [offline access codes](https://docs.seam.co/low-level-apis/smart-locks/access-codes#offline-access-codes). Offline access (PIN) codes are designed for door locks that might not always maintain an internet connection. For this type of access code, the device manufacturer uses encryption keys (tokens) to create server-based registries of algorithmically-generated offline PIN codes. Because the tokens remain synchronized with the managed devices, the locks do not require an active internet connection—and you do not need to be near the locks—to create an offline access code. Then, owners or managers can share these offline codes with users through a variety of mechanisms, such as messaging applications. That is, lock users do not need to install a smartphone application to receive an offline access code.
+    In addition, for certain devices, Seam also supports `offline access codes <https://docs.seam.co/low-level-apis/smart-locks/access-codes#offline-access-codes>`_. Offline access (PIN) codes are designed for door locks that might not always maintain an internet connection. For this type of access code, the device manufacturer uses encryption keys (tokens) to create server-based registries of algorithmically-generated offline PIN codes. Because the tokens remain synchronized with the managed devices, the locks do not require an active internet connection—and you do not need to be near the locks—to create an offline access code. Then, owners or managers can share these offline codes with users through a variety of mechanisms, such as messaging applications. That is, lock users do not need to install a smartphone application to receive an offline access code.
 
-    For granting a person access to a space, [Access Grants](https://docs.seam.co/use-cases/granting-access) are the default and recommended approach and work across both standalone smart locks and access systems. Use the lower-level Access Codes API directly only when you specifically need to manage individual PIN codes.
+    For granting a person access to a space, `Access Grants <https://docs.seam.co/use-cases/granting-access>`_ are the default and recommended approach and work across both standalone smart locks and access systems. Use the lower-level Access Codes API directly only when you specifically need to manage individual PIN codes.
 
     :ivar access_code_id: Unique identifier for the access code.
     :vartype access_code_id: str
@@ -36,7 +36,7 @@ class AccessCode:
     :ivar ends_at: Date and time after which the time-bound access code becomes inactive.
     :vartype ends_at: str
 
-    :ivar errors: Errors associated with the [access code](https://docs.seam.co/low-level-apis/smart-locks/access-codes).
+    :ivar errors: Errors associated with the `access code <https://docs.seam.co/low-level-apis/smart-locks/access-codes>`_.
     :vartype errors: List[Dict[str, Any]]
 
     :ivar is_backup: Indicates whether the access code is a backup code.
@@ -51,10 +51,10 @@ class AccessCode:
     :ivar is_managed: Indicates whether Seam manages the access code.
     :vartype is_managed: bool
 
-    :ivar is_offline_access_code: Indicates whether the access code is intended for use in offline scenarios. If `true`, this code can be created on a device without a network connection.
+    :ivar is_offline_access_code: Indicates whether the access code is intended for use in offline scenarios. If ``true``, this code can be created on a device without a network connection.
     :vartype is_offline_access_code: bool
 
-    :ivar is_one_time_use: Indicates whether the access code can only be used once. If `true`, the code becomes invalid after the first use.
+    :ivar is_one_time_use: Indicates whether the access code can only be used once. If ``true``, the code becomes invalid after the first use.
     :vartype is_one_time_use: bool
 
     :ivar is_scheduled_on_device: Indicates whether the code is set on the device according to a preconfigured schedule.
@@ -63,7 +63,7 @@ class AccessCode:
     :ivar is_waiting_for_code_assignment: Indicates whether the access code is waiting for a code assignment.
     :vartype is_waiting_for_code_assignment: bool
 
-    :ivar name: Name of the access code. Enables administrators and users to identify the access code easily, especially when there are numerous access codes. Note that the name provided on Seam is used to identify the code on Seam and is not necessarily the name that will appear in the lock provider's app or on the device. This is because lock providers may have constraints on names, such as length, uniqueness, or characters that can be used. In addition, some lock providers may break down names into components such as `first_name` and `last_name`. To provide a consistent experience, Seam identifies the code on Seam by its name but may modify the name that appears on the lock provider's app or on the device. For example, Seam may add additional characters or truncate the name to meet provider constraints. To help your users identify codes set by Seam, Seam provides the name exactly as it appears on the lock provider's app or on the device as a separate property called `appearance`. This is an object with a `name` property and, optionally, `first_name` and `last_name` properties (for providers that break down a name into components).
+    :ivar name: Name of the access code. Enables administrators and users to identify the access code easily, especially when there are numerous access codes. Note that the name provided on Seam is used to identify the code on Seam and is not necessarily the name that will appear in the lock provider's app or on the device. This is because lock providers may have constraints on names, such as length, uniqueness, or characters that can be used. In addition, some lock providers may break down names into components such as ``first_name`` and ``last_name``. To provide a consistent experience, Seam identifies the code on Seam by its name but may modify the name that appears on the lock provider's app or on the device. For example, Seam may add additional characters or truncate the name to meet provider constraints. To help your users identify codes set by Seam, Seam provides the name exactly as it appears on the lock provider's app or on the device as a separate property called ``appearance``. This is an object with a ``name`` property and, optionally, ``first_name`` and ``last_name`` properties (for providers that break down a name into components).
     :vartype name: str
 
     :ivar pending_mutations: Collection of pending mutations for the access code. Indicates changes that Seam is in the process of pushing to the device.
@@ -75,13 +75,13 @@ class AccessCode:
     :ivar starts_at: Date and time at which the time-bound access code becomes active.
     :vartype starts_at: str
 
-    :ivar status: Current status of the access code within the operational lifecycle. Values are `setting`, a transitional phase that indicates that the code is being configured or activated; `set`, which indicates that the code is active and operational; `unset`, which indicates a deactivated or unused state, either before activation or after deliberate deactivation; `removing`, which indicates a transitional period in which the code is being deleted or made inactive; and `unknown`, which indicates an indeterminate state, due to reasons such as system errors or incomplete data, that highlights a potential need for system review or troubleshooting. See also [Lifecycle of Access Codes](https://docs.seam.co/low-level-apis/smart-locks/access-codes/lifecycle-of-access-codes).
+    :ivar status: Current status of the access code within the operational lifecycle. Values are ``setting``, a transitional phase that indicates that the code is being configured or activated; ``set``, which indicates that the code is active and operational; ``unset``, which indicates a deactivated or unused state, either before activation or after deliberate deactivation; ``removing``, which indicates a transitional period in which the code is being deleted or made inactive; and ``unknown``, which indicates an indeterminate state, due to reasons such as system errors or incomplete data, that highlights a potential need for system review or troubleshooting. See also `Lifecycle of Access Codes <https://docs.seam.co/low-level-apis/smart-locks/access-codes/lifecycle-of-access-codes>`_.
     :vartype status: str
 
-    :ivar type: Type of the access code. `ongoing` access codes are active continuously until deactivated manually. `time_bound` access codes have a specific duration.
+    :ivar type: Type of the access code. ``ongoing`` access codes are active continuously until deactivated manually. ``time_bound`` access codes have a specific duration.
     :vartype type: str
 
-    :ivar warnings: Warnings associated with the [access code](https://docs.seam.co/low-level-apis/smart-locks/access-codes).
+    :ivar warnings: Warnings associated with the `access code <https://docs.seam.co/low-level-apis/smart-locks/access-codes>`_.
     :vartype warnings: List[Dict[str, Any]]
 
     :ivar workspace_id: Unique identifier for the Seam workspace associated with the access code.

seam/resources/access_grant.py

@@ -31,13 +31,13 @@ class AccessGrant:
     :ivar ends_at: Date and time at which the Access Grant ends.
     :vartype ends_at: str
 
-    :ivar errors: Errors associated with the [access grant](https://docs.seam.co/use-cases/granting-access).
+    :ivar errors: Errors associated with the `access grant <https://docs.seam.co/use-cases/granting-access>`_.
     :vartype errors: List[Dict[str, Any]]
 
     :ivar instant_key_url: Instant Key URL. Only returned if the Access Grant has a single mobile_key access_method.
     :vartype instant_key_url: str
 
-    :ivar location_ids: Deprecated: Use `space_ids`.
+    :ivar location_ids: Deprecated: Use ``space_ids``.
     :vartype location_ids: List[str]
 
     :ivar name: Name of the Access Grant. If not provided, the display name will be computed.
@@ -61,7 +61,7 @@ class AccessGrant:
     :ivar user_identity_id: ID of user identity to which the Access Grant gives access.
     :vartype user_identity_id: str
 
-    :ivar warnings: Warnings associated with the [access grant](https://docs.seam.co/use-cases/granting-access).
+    :ivar warnings: Warnings associated with the `access grant <https://docs.seam.co/use-cases/granting-access>`_.
     :vartype warnings: List[Dict[str, Any]]
 
     :ivar workspace_id: ID of the Seam workspace associated with the Access Grant.

seam/resources/access_method.py

@@ -25,7 +25,7 @@ class AccessMethod:
     :ivar display_name: Display name of the access method.
     :vartype display_name: str
 
-    :ivar errors: Errors associated with the [access method](https://docs.seam.co/use-cases/granting-access/creating-an-access-grant).
+    :ivar errors: Errors associated with the `access method <https://docs.seam.co/use-cases/granting-access/creating-an-access-grant>`_.
     :vartype errors: List[Dict[str, Any]]
 
     :ivar instant_key_url: URL of the Instant Key for mobile key access methods.
@@ -49,13 +49,13 @@ class AccessMethod:
     :ivar issued_at: Date and time at which the access method was issued.
     :vartype issued_at: str
 
-    :ivar mode: Access method mode. Supported values: `code`, `card`, `mobile_key`, `cloud_key`.
+    :ivar mode: Access method mode. Supported values: ``code``, ``card``, ``mobile_key``, ``cloud_key``.
     :vartype mode: str
 
-    :ivar pending_mutations: Pending mutations for the [access method](https://docs.seam.co/use-cases/granting-access/creating-an-access-grant). Indicates operations that are in progress.
+    :ivar pending_mutations: Pending mutations for the `access method <https://docs.seam.co/use-cases/granting-access/creating-an-access-grant>`_. Indicates operations that are in progress.
     :vartype pending_mutations: List[Dict[str, Any]]
 
-    :ivar warnings: Warnings associated with the [access method](https://docs.seam.co/use-cases/granting-access/creating-an-access-grant).
+    :ivar warnings: Warnings associated with the `access method <https://docs.seam.co/use-cases/granting-access/creating-an-access-grant>`_.
     :vartype warnings: List[Dict[str, Any]]
 
     :ivar workspace_id: ID of the Seam workspace associated with the access method.