style: single backticks in docstrings

Replace rST-style double backticks with single backticks
across docstrings to match project convention. Preserve
double backticks where the wrapped text itself contains
backtick characters (literal markdown syntax examples).

Fix D301 in type_format.py with a raw docstring for
backslash content.

Signed-off-by: Seth Fitzsimmons <sethfitz@amazon.com>

Author: sethfitz

packages/overture-schema-codegen/src/overture/schema/codegen/extraction/examples.py

@@ -41,10 +41,10 @@ def _inject_literal_fields(
 ) -> dict[str, Any]:
     """Inject single-value Literal field defaults missing from *data*.
 
-    Inspects *model_fields_dict* for fields with single-value ``Literal``
+    Inspects *model_fields_dict* for fields with single-value `Literal`
     annotations. For each field missing from *data*, injects the literal
-    value using the field's ``validation_alias`` (if set), falling back
-    to ``alias``, then to the field name.
+    value using the field's `validation_alias` (if set), falling back
+    to `alias`, then to the field name.
 
     Returns a new dict; the original is not mutated.
     """
@@ -149,11 +149,11 @@ def sort_key(row: tuple[str, Any]) -> int:
 
 
 def _structured_fields(value: object) -> list[tuple[str, Any]] | None:
-    """Extract named fields from ``__slots__``-based types like BBox.
+    """Extract named fields from `__slots__`-based types like BBox.
 
-    Returns a list of ``(name, value)`` pairs for types that expose
-    public properties backed by private slots (``_name`` -> ``name``).
-    Returns ``None`` for types without this pattern.
+    Returns a list of `(name, value)` pairs for types that expose
+    public properties backed by private slots (`_name` -> `name`).
+    Returns `None` for types without this pattern.
     """
     cls = type(value)
     slots = getattr(cls, "__slots__", ())
@@ -238,9 +238,9 @@ def augment_missing_fields(
 ) -> list[tuple[str, Any]]:
     """Add (name, None) entries for fields absent from *rows*.
 
-    Compares base field names (via ``extract_base_field``) against
+    Compares base field names (via `extract_base_field`) against
     *field_names*. Fields in *field_names* not represented in *rows*
-    are appended as ``(name, None)``. Handles dot-notation and bracket-
+    are appended as `(name, None)`. Handles dot-notation and bracket-
     notation keys correctly.
 
     Parameters
@@ -267,7 +267,7 @@ def load_examples_from_toml(
     pyproject_path: Path,
     model_name: str,
 ) -> list[dict[str, Any]]:
-    """Load ``[examples.<model_name>]`` from a pyproject.toml file."""
+    """Load `[examples.<model_name>]` from a pyproject.toml file."""
     with pyproject_path.open("rb") as f:
         data = tomllib.load(f)
 

packages/overture-schema-codegen/src/overture/schema/codegen/extraction/model_extraction.py

@@ -24,7 +24,7 @@
 def resolve_field_alias(field_name: str, field_info: FieldInfo) -> str:
     """Return the data-dict key for a Pydantic field.
 
-    Prefers ``validation_alias``, falls back to ``alias``, then the
+    Prefers `validation_alias`, falls back to `alias`, then the
     Python field name. Only string aliases are supported; AliasPath
     and AliasChoices are ignored.
     """
@@ -153,10 +153,10 @@ def expand_model_tree(
 ) -> FeatureSpec:
     """Populate model references on MODEL-kind fields, recursively.
 
-    Walks *spec*'s fields and sets ``field.model`` for fields whose type
+    Walks *spec*'s fields and sets `field.model` for fields whose type
     is a Pydantic model. Uses *cache* to reuse already-extracted ModelSpecs
     and detect shared references. Marks fields whose model creates a cycle
-    in the ancestor chain with ``starts_cycle=True``.
+    in the ancestor chain with `starts_cycle=True`.
 
     Mutates *spec* in place and returns it.
     """

packages/overture-schema-codegen/src/overture/schema/codegen/extraction/specs.py

@@ -39,7 +39,7 @@ class TypeIdentity:
 
     Pairs a unique Python object (class, NewType callable, or union
     annotation) with its display name. Equality and hashing delegate
-    to ``obj`` identity so registry lookups work regardless of how
+    to `obj` identity so registry lookups work regardless of how
     the display name was derived.
     """
 
@@ -65,12 +65,12 @@ def module(self) -> str:
 
 
 class _SourceTypeIdentityMixin:
-    """Mixin providing ``identity`` from ``source_type`` and ``name``.
+    """Mixin providing `identity` from `source_type` and `name`.
 
     Shared by EnumSpec, ModelSpec, NewTypeSpec, and PydanticTypeSpec --
-    each has a ``source_type`` (the Python class/callable) and a ``name``.
-    UnionSpec uses ``source_annotation`` instead, so it defines its
-    own ``identity``.
+    each has a `source_type` (the Python class/callable) and a `name`.
+    UnionSpec uses `source_annotation` instead, so it defines its
+    own `identity`.
     """
 
     source_type: object | None
@@ -225,7 +225,7 @@ def docs_url(self) -> str:
 
 
 def is_pydantic_sourced(source_type: type | None) -> bool:
-    """Check whether *source_type* originates from the ``pydantic`` package."""
+    """Check whether *source_type* originates from the `pydantic` package."""
     return getattr(source_type, "__module__", "").startswith("pydantic")
 
 

packages/overture-schema-codegen/src/overture/schema/codegen/extraction/type_analyzer.py

@@ -79,8 +79,8 @@ def walk_type_info(ti: TypeInfo, visitor: Callable[[TypeInfo], None]) -> None:
     """Call *visitor* on *ti*, then recurse into dict key/value types.
 
     Captures the shared recursive descent pattern used by type collection
-    and reverse reference computation. Union members are ``type`` objects
-    (not ``TypeInfo``), so callers handle them directly.
+    and reverse reference computation. Union members are `type` objects
+    (not `TypeInfo`), so callers handle them directly.
     """
     visitor(ti)
     if ti.dict_key_type is not None:
@@ -108,13 +108,13 @@ class _UnwrapState:
     """Accumulated state from iterative type unwrapping.
 
     Tracks NewType names and refs during unwrapping:
-    - ``outermost_newtype_name`` / ``outermost_newtype_ref``: the first
-      NewType encountered, exposed as ``TypeInfo.newtype_name`` / ``newtype_ref``.
-    - ``last_newtype_name``: the most recently entered NewType name, used
-      as the resolved ``base_type`` for the terminal type.
-    - ``last_newtype_ref``: the most recently entered NewType callable,
+    - `outermost_newtype_name` / `outermost_newtype_ref`: the first
+      NewType encountered, exposed as `TypeInfo.newtype_name` / `newtype_ref`.
+    - `last_newtype_name`: the most recently entered NewType name, used
+      as the resolved `base_type` for the terminal type.
+    - `last_newtype_ref`: the most recently entered NewType callable,
       used as constraint provenance (which NewType contributed each constraint).
-    - ``newtype_outer_list_depth``: list layers accumulated before entering
+    - `newtype_outer_list_depth`: list layers accumulated before entering
       the outermost NewType boundary.
     """
 
@@ -329,7 +329,7 @@ def single_literal_value(annotation: object) -> object | None:
     Delegates to analyze_type for all unwrapping, then checks
     whether the result is a single-value Literal. Multi-value
     Literals return None — callers needing all values should use
-    ``analyze_type`` and read ``literal_values`` directly.
+    `analyze_type` and read `literal_values` directly.
     """
     try:
         ti = analyze_type(annotation)

packages/overture-schema-codegen/src/overture/schema/codegen/layout/module_layout.py

@@ -25,7 +25,7 @@
 
 
 def _split_entry_point(entry_point_path: str) -> tuple[str, str]:
-    """Split ``"module.path:ClassName"`` into its two parts.
+    """Split `"module.path:ClassName"` into its two parts.
 
     >>> _split_entry_point("overture.schema.buildings:Building")
     ('overture.schema.buildings', 'Building')
@@ -98,7 +98,7 @@ def is_package_module(
 ) -> bool:
     """Check whether a module is a package (directory) or a file module.
 
-    Packages have ``__path__``; file modules do not (PEP 302).
+    Packages have `__path__`; file modules do not (PEP 302).
     """
     registry: Mapping[str, object] = (
         module_registry if module_registry is not None else sys.modules
@@ -134,7 +134,7 @@ def compute_output_dir(
     """Compute output directory for a module, mirroring package structure.
 
     File modules drop their last component (the .py filename).
-    Packages keep all components. Returns ``PurePosixPath(".")`` for
+    Packages keep all components. Returns `PurePosixPath(".")` for
     the root directory.
     """
     relpath = module_relpath(module, schema_root)

packages/overture-schema-codegen/src/overture/schema/codegen/markdown/link_computation.py

@@ -39,7 +39,7 @@ def _is_normalized(path: PurePosixPath) -> bool:
 def relative_link(source: PurePosixPath, target: PurePosixPath) -> str:
     """Compute a relative path from source file to target file.
 
-    Both paths must be normalized (no ``..`` components) and relative
+    Both paths must be normalized (no `..` components) and relative
     to the same output root.
     """
     if not _is_normalized(source):

packages/overture-schema-codegen/src/overture/schema/codegen/markdown/path_assignment.py

@@ -95,10 +95,10 @@ def _aggregate_page_entries(
 def _nest_under_types(
     output_dir: PurePosixPath, feature_dirs: set[PurePosixPath]
 ) -> PurePosixPath:
-    """Insert ``types/`` after the feature directory portion.
+    """Insert `types/` after the feature directory portion.
 
     If *output_dir* equals or is a subdirectory of a feature directory,
-    returns a path with ``types/`` inserted after the feature directory.
+    returns a path with `types/` inserted after the feature directory.
     Otherwise returns *output_dir* unchanged.
     """
     for fd in sorted(feature_dirs, key=lambda p: len(p.parts), reverse=True):

packages/overture-schema-codegen/src/overture/schema/codegen/markdown/renderer.py

@@ -65,10 +65,10 @@
 def _linkify_bare_urls(text: str) -> str:
     """Wrap bare URLs in Markdown link syntax.
 
-    Turns ``www.example.com`` into ``[www.example.com](https://www.example.com)``
-    and ``https://example.com`` into ``[https://example.com](https://example.com)``.
-    URLs already inside ``[text](url)`` or backtick code spans are left
-    untouched. Trailing sentence punctuation (``.``, ``,``, etc.) is excluded
+    Turns `www.example.com` into `[www.example.com](https://www.example.com)`
+    and `https://example.com` into `[https://example.com](https://example.com)`.
+    URLs already inside `[text](url)` or backtick code spans are left
+    untouched. Trailing sentence punctuation (`.`, `,`, etc.) is excluded
     from the link.
 
     Two-pass approach: extract code spans first, linkify the remaining
@@ -118,7 +118,7 @@ def _get_jinja_env() -> Environment:
 class _FieldRow(TypedDict):
     """Template context for a single field table row.
 
-    ``pre_formatted`` indicates the ``name`` already contains backticks
+    `pre_formatted` indicates the `name` already contains backticks
     and variant tags, so the template should render it verbatim.
     """
 
@@ -135,7 +135,7 @@ def _unwrap_paragraphs(text: str) -> str:
     r"""Unwrap hard-wrapped lines within paragraphs, preserving paragraph breaks.
 
     Splits on blank lines (paragraph boundaries), replaces single newlines
-    within each paragraph with spaces, then rejoins with ``\n\n``.
+    within each paragraph with spaces, then rejoins with `\n\n`.
     Matches markdown's treatment of newlines within paragraphs.
     """
     paragraphs = _PARAGRAPH_BREAK_RE.split(text)
@@ -146,8 +146,8 @@ def _sanitize_for_table_cell(text: str) -> str:
     """Sanitize text for embedding in a markdown table cell.
 
     Unwraps within-paragraph newlines to spaces, then converts paragraph
-    breaks to ``<br/><br/>``. Escapes pipe characters for table safety.
-    Uses ``<br/>`` (not ``<br>``) for MDX/Docusaurus compatibility.
+    breaks to `<br/><br/>`. Escapes pipe characters for table safety.
+    Uses `<br/>` (not `<br>`) for MDX/Docusaurus compatibility.
     """
     text = text.strip()
     text = _unwrap_paragraphs(text)
@@ -156,7 +156,7 @@ def _sanitize_for_table_cell(text: str) -> str:
 
 
 def _truncate(text: str) -> str:
-    """Truncate text to ``_EXAMPLE_TRUNCATION_LIMIT`` chars, adding ellipsis."""
+    """Truncate text to `_EXAMPLE_TRUNCATION_LIMIT` chars, adding ellipsis."""
     if len(text) > _EXAMPLE_TRUNCATION_LIMIT:
         return text[: _EXAMPLE_TRUNCATION_LIMIT - 3] + "..."
     return text
@@ -255,7 +255,7 @@ def _annotate_field_constraints(
 
 
 def _expandable_list_suffix(field_spec: FieldSpec) -> str:
-    """Return ``"[]"`` per nesting level for list-of-model fields expanded inline."""
+    """Return `"[]"` per nesting level for list-of-model fields expanded inline."""
     if (
         field_spec.type_info.is_list
         and field_spec.model
@@ -340,7 +340,7 @@ def _short_variant_name(class_name: str, union_name: str) -> str:
 
 
 def _variant_tag(annotated: AnnotatedField, union_name: str) -> str | None:
-    """Return an italic variant tag like ``*(Road, Water)*``, or None for shared fields."""
+    """Return an italic variant tag like `*(Road, Water)*`, or None for shared fields."""
     if annotated.variant_sources is None:
         return None
     short_names = [
@@ -535,7 +535,7 @@ def render_pydantic_type(
 def _format_bound(value: int | float) -> str:
     """Format a numeric bound for display.
 
-    Uses ``2^63`` notation for int64-scale values to avoid unreadable
+    Uses `2^63` notation for int64-scale values to avoid unreadable
     numbers; otherwise formats with thousands separators for ints.
     """
     if value == _INT64_MIN:
@@ -550,7 +550,7 @@ def _format_bound(value: int | float) -> str:
 def _format_interval(bounds: Interval) -> str:
     """Format an Interval as a range string, or empty if unconstrained.
 
-    Two inclusive bounds render as ``lower to upper``. All other
+    Two inclusive bounds render as `lower to upper`. All other
     combinations use explicit comparison operators so the
     inclusivity/exclusivity is unambiguous.
     """

packages/overture-schema-codegen/src/overture/schema/codegen/markdown/type_format.py

@@ -18,7 +18,7 @@
 
 
 def _code_link(name: str, href: str) -> str:
-    """Format a markdown link with inline-code text: [``name``](href)."""
+    """Format a markdown link with inline-code text: [`name`](href)."""
     return f"[`{name}`]({href})"
 
 
@@ -38,10 +38,10 @@ def resolve_type_link(identity: TypeIdentity, ctx: LinkContext | None = None) ->
 
 
 def _wrap_list_n(inner: str, depth: int) -> str:
-    """Wrap an inner type string in ``list<...>`` markdown syntax *depth* times.
+    """Wrap an inner type string in `list<...>` markdown syntax *depth* times.
 
     Builds a single broken-backtick wrapper rather than nesting iteratively.
-    Iterative nesting creates adjacent backticks (`````) that CommonMark
+    Iterative nesting creates adjacent backticks that CommonMark
     interprets as multi-backtick code span delimiters.
     """
     return f"`{'list<' * depth}`{inner}`{'>' * depth}`"
@@ -69,7 +69,7 @@ def _try_primitive_link(
 
     Registered primitives (int32, Geometry) and Pydantic types (HttpUrl)
     can have pages in the registry. Uses the type registry display name
-    (e.g. ``geometry`` not ``Geometry``) for the link text.
+    (e.g. `geometry` not `Geometry`) for the link text.
     """
     if ti.kind != TypeKind.PRIMITIVE or not ctx:
         return None
@@ -85,15 +85,15 @@ def _try_primitive_link(
 def _markdown_type_name(ti: TypeInfo) -> str:
     """Return the markdown display name for a type.
 
-    Uses the semantic NewType name when present (e.g. ``LanguageTag``),
-    otherwise falls back to the resolved markdown type (e.g. ``string``).
+    Uses the semantic NewType name when present (e.g. `LanguageTag`),
+    otherwise falls back to the resolved markdown type (e.g. `string`).
     """
     name = ti.newtype_name if is_semantic_newtype(ti) else None
     return name or resolve_type_name(ti, "markdown")
 
 
 def format_dict_type(ti: TypeInfo) -> str:
-    """Format a dict TypeInfo as bare ``map<K, V>`` using resolved markdown names."""
+    """Format a dict TypeInfo as bare `map<K, V>` using resolved markdown names."""
     if ti.dict_key_type is None or ti.dict_value_type is None:
         msg = f"format_dict_type requires dict key/value types, got {ti}"
         raise ValueError(msg)
@@ -111,7 +111,7 @@ def _format_union_members(
 
     Each member is resolved independently so members with pages get linked
     while others render as plain code spans. *separator* is inserted between
-    members (default is ``\|`` for table-cell safety).
+    members (default is `\|` for table-cell safety).
     """
     return separator.join(resolve_type_link(TypeIdentity.of(m), ctx) for m in members)
 
@@ -184,7 +184,7 @@ def _linked_or_backticked(ti: TypeInfo, ctx: LinkContext | None) -> tuple[str, b
     need broken-backtick formatting (interleaving backtick runs with
     linked text).
 
-    When ``has_link`` is True, ``formatted_string`` is a markdown link
+    When `has_link` is True, `formatted_string` is a markdown link
     ready for broken-backtick container syntax. When False, it is a raw
     name that the caller embeds inside backticks.
     """

packages/overture-schema-codegen/tests/test_example_loader.py

@@ -196,7 +196,7 @@ def mock_project(tmp_path: Path) -> Iterator[MockProject]:
 
     Yields a MockProject with root, pyproject path, and mod_name.
     Writes a minimal pyproject.toml by default; tests can overwrite via
-    ``project.write_pyproject()``.
+    `project.write_pyproject()`.
     """
     root = tmp_path / "project"
     root.mkdir()