@mintlify/scraping 4.0.1191 → 4.0.1193

package/__test__/sdk-sphinx-images.test.ts

@@ -0,0 +1,79 @@
+import { resolveRelativeUrl } from '@mintlify/common';
+import type { Element } from 'hast';
+import { visit } from 'unist-util-visit';
+import { describe, expect, it } from 'vitest';
+
+import { htmlToHast } from '../src/pipeline/root.js';
+import { hastToMdx, parseMarkdown } from '../src/sdk/convert.js';
+import { rewriteSphinxImages } from '../src/sdk/sphinx-images.js';
+
+function imageSource(src: string, source: string, destination: string): string {
+  const tree = htmlToHast(`<img src="${src}" alt="Synthetic diagram" title="Flow chart">`);
+  rewriteSphinxImages(tree, source, destination);
+  const sources: string[] = [];
+  visit(parseMarkdown(hastToMdx(tree)), 'image', (node) => sources.push(node.url));
+  const converted = sources[0];
+  if (converted === undefined) throw new Error('Missing converted image');
+  return converted;
+}
+
+function resolvedImage(slug: string, src: string): string {
+  const page = `sdk/${slug}`;
+  return new URL(resolveRelativeUrl(page, src, false), `https://docs.example.test/${page}`).href;
+}
+
+describe('rewriteSphinxImages', () => {
+  it('keeps split module images pointing to the asset used by the original page', () => {
+    const before = imageSource('./images/flow.png', 'api', 'api');
+    const after = imageSource('./images/flow.png', 'api', 'api/sample.client');
+    expect(after).toBe('../images/flow.png');
+    expect(resolvedImage('api/sample.client', after)).toBe(resolvedImage('api', before));
+    expect(resolvedImage('api/sample.client', after)).toBe(
+      'https://docs.example.test/sdk/images/flow.png'
+    );
+  });
+
+  it.each([
+    ['../_images/flow.png', 'api', 'api/sample.client'],
+    ['../_images/flow.png', 'guides/api', 'guides/api/sample.client'],
+    ['./images/flow.png', 'api/index', 'api/index/sample.client'],
+    ['images/flow.png', 'api', 'api/sample.client'],
+    ['./images/flow%20chart.png?view=wide#detail', 'api', 'api/sample.client'],
+    ['./images/flow.png', 'guides/api', 'reference'],
+  ])('preserves asset identity for %s moved from %s to %s', (src, source, destination) => {
+    const before = imageSource(src, source, source);
+    const after = imageSource(src, source, destination);
+    expect(resolvedImage(destination, after)).toBe(resolvedImage(source, before));
+  });
+
+  it.each([
+    '/images/flow.svg?view=wide#detail',
+    'https://assets.example.test/flow.svg?view=wide#detail',
+    '//assets.example.test/flow.svg',
+    'data:image/svg+xml,%3Csvg%3E%3C/svg%3E',
+    'javascript:alert(1)',
+    '#diagram',
+    '?version=1',
+  ])('preserves existing non-file image references: %s', (src) => {
+    const tree = htmlToHast('<img alt="Synthetic diagram">');
+    const images: Element[] = [];
+    visit(tree, 'element', (node: Element) => {
+      if (node.tagName === 'img') {
+        node.properties.src = src;
+        images.push(node);
+      }
+    });
+    rewriteSphinxImages(tree, 'api', 'api/sample.client');
+    expect(images[0]?.properties.src).toBe(src);
+  });
+
+  it('retains image metadata and unrelated links', () => {
+    const tree = htmlToHast(
+      '<p><a href="./guide.html">Guide</a><img src="./images/flow.png" alt="Synthetic diagram" title="Flow chart"></p>'
+    );
+    rewriteSphinxImages(tree, 'api', 'api/sample.client');
+    const content = hastToMdx(tree);
+    expect(content).toContain('[Guide](./guide.html)');
+    expect(content).toContain('![Synthetic diagram](../images/flow.png "Flow chart")');
+  });
+});

package/__test__/sdk-sphinx-modules.test.ts

@@ -0,0 +1,97 @@
+import { describe, expect, it } from 'vitest';
+
+import { splitSphinxModules } from '../src/sdk/sphinx-modules.js';
+import type { SphinxNavigationDoc } from '../src/sdk/sphinx-navigation.js';
+
+const clientSection =
+  '<section id="module-sample.clients"><span id="clients-module"></span><h2>Client module<a class="headerlink" href="#module-sample.clients">¶</a></h2><dl class="py class"><dt class="sig" id="sample.clients.Client">Client</dt><dd>Client documentation.<dl class="py method"><dt class="sig" id="sample.clients.Client.send">send</dt><dt class="sig" id="sample.clients.Client.send-1">send overload</dt></dl></dd></dl></section>';
+const modelSection =
+  '<section id="module-sample.models"><h2>Models module</h2><dl class="py class"><dt class="sig" id="sample.models.Request">Request</dt><dd>Request documentation.</dd></dl></section>';
+
+function combined(body = `${clientSection}${modelSection}`): SphinxNavigationDoc {
+  return {
+    slug: 'api',
+    title: 'Sample API',
+    body: `<section id="api"><h1>Sample API</h1><p>API introduction.</p>${body}<p>API footer.</p></section>`,
+    tag: 'MODULE',
+  };
+}
+
+describe('splitSphinxModules', () => {
+  it('splits peer modules with stable routes and preserves their original source metadata', () => {
+    const [overview, clients, models] = splitSphinxModules([combined()]);
+
+    expect(clients).toMatchObject({
+      slug: 'api/sample.clients',
+      title: 'Client module',
+      body: clientSection,
+      sourceSlug: 'api',
+      tag: 'MODULE',
+      parents: [{ link: '/api' }],
+    });
+    expect(models).toMatchObject({
+      slug: 'api/sample.models',
+      title: 'Models module',
+      body: modelSection,
+      sourceSlug: 'api',
+    });
+    expect(overview?.slug).toBe('api');
+    expect(overview?.tag).toBe('MODULE');
+    expect(overview?.body).toContain('<h1>Sample API</h1><p>API introduction.</p>');
+    expect(overview?.body).toContain('<p>API footer.</p>');
+    expect(overview?.body).toContain('href="/api/sample.clients">Client module</a>');
+    expect(overview?.body).toContain('href="/api/sample.models">Models module</a>');
+    expect(overview?.body).not.toContain('Client documentation.');
+    expect(overview?.body).not.toContain('Request documentation.');
+  });
+
+  it('keeps original module, symbol, and overload anchors on the overview for existing URLs', () => {
+    const [overview] = splitSphinxModules([combined()]);
+    for (const id of [
+      'module-sample.clients',
+      'clients-module',
+      'sample.clients.Client',
+      'sample.clients.Client.send',
+      'sample.clients.Client.send-1',
+      'sample.models.Request',
+    ]) {
+      expect(overview?.body).toContain(`<span id="${id}"></span>`);
+    }
+  });
+
+  it('supports legacy Sphinx module sections without splitting nested modules twice', () => {
+    const nested =
+      '<section id="module-sample.clients.nested"><h3>Nested module</h3><p>Nested documentation.</p></section>';
+    const legacyClients = `<div class="section" id="module-sample.clients"><h2>Client module</h2>${nested}</div>`;
+    const docs = splitSphinxModules([combined(`${legacyClients}${modelSection}`)]);
+
+    expect(docs.map((doc) => doc.slug)).toEqual(['api', 'api/sample.clients', 'api/sample.models']);
+    expect(docs[1]?.body).toBe(legacyClients);
+    expect(docs[0]?.body).toContain('id="module-sample.clients.nested"');
+  });
+
+  it('leaves single-module pages unchanged', () => {
+    const original = combined(clientSection);
+    expect(splitSphinxModules([original])).toEqual([original]);
+  });
+
+  it('keeps original pages when a generated module route already exists', () => {
+    const original = combined();
+    const existing = {
+      slug: 'api/sample.clients',
+      title: 'Authored clients',
+      body: '<p>Authored content.</p>',
+    };
+    expect(splitSphinxModules([original, existing])).toEqual([original, existing]);
+  });
+
+  it('does not create colliding pages from duplicate module identifiers', () => {
+    const original = combined(`${clientSection}${clientSection}`);
+    expect(splitSphinxModules([original])).toEqual([original]);
+  });
+
+  it('does not treat isolated module sections in separate containers as peer modules', () => {
+    const original = combined(`<div>${clientSection}</div><div>${modelSection}</div>`);
+    expect(splitSphinxModules([original])).toEqual([original]);
+  });
+});

package/__test__/sdk-sphinx-navigation.test.ts

@@ -0,0 +1,318 @@
+import { describe, expect, it } from 'vitest';
+
+import { buildSphinxNavigation, type SphinxNavigationDoc } from '../src/sdk/sphinx-navigation.js';
+import type { SdkNavGroup } from '../src/sdk/types.js';
+
+function doc(
+  slug: string,
+  title: string,
+  body = '',
+  tag?: string,
+  toc?: string
+): SphinxNavigationDoc {
+  return { slug, title, body, tag, toc };
+}
+
+function pages(groups: SdkNavGroup[]): string[] {
+  return groups.flatMap((group) =>
+    group.pages.flatMap((page) => (typeof page === 'string' ? [page] : pages([page])))
+  );
+}
+
+describe('buildSphinxNavigation', () => {
+  it('preserves nested toctrees and puts module indexes with their reference pages', () => {
+    const groups = buildSphinxNavigation([
+      doc(
+        'index',
+        'Example SDK',
+        '<div class="toctree-wrapper"><ul><li><a href="modules.html">Modules</a><ul><li><a href="example.html">Example package</a><ul><li><a href="example.zeta.html">Zeta</a></li><li><a href="example.alpha.html">Alpha</a></li></ul></li></ul></li></ul></div>'
+      ),
+      doc('modules', 'Modules'),
+      doc('example', 'Example package', '', 'MODULE'),
+      doc('example.alpha', 'Alpha module', '', 'MODULE'),
+      doc('example.zeta', 'Zeta module', '', 'MODULE'),
+    ]);
+
+    expect(groups).toEqual([
+      {
+        group: 'API Reference',
+        pages: [
+          {
+            group: 'Example SDK',
+            pages: [
+              'index',
+              {
+                group: 'Modules',
+                pages: [
+                  'modules',
+                  {
+                    group: 'Example package',
+                    pages: ['example', 'example.zeta', 'example.alpha'],
+                  },
+                ],
+              },
+            ],
+          },
+        ],
+      },
+    ]);
+  });
+
+  it('keeps authored guides apart from reference hierarchy in a mixed root toctree', () => {
+    const groups = buildSphinxNavigation([
+      doc(
+        'index',
+        'Example SDK',
+        '<p>Build an application with this SDK.</p><div class="toctree-wrapper"><ul><li><a href="quickstart.html">Quickstart</a></li><li><a href="api/index.html">API reference</a><ul><li><a href="api/client.html">Client</a></li></ul></li></ul></div>'
+      ),
+      doc('quickstart', 'Quickstart', '<p>Install the SDK.</p>'),
+      doc('api/index', 'API reference'),
+      doc('api/client', 'Client module', '', 'MODULE'),
+    ]);
+
+    expect(groups).toEqual([
+      {
+        group: 'Getting Started',
+        pages: [{ group: 'Example SDK', pages: ['index', 'quickstart'] }],
+      },
+      {
+        group: 'API Reference',
+        pages: [{ group: 'API reference', pages: ['api/index', 'api/client'] }],
+      },
+    ]);
+  });
+
+  it('uses per-page toctrees and relative URLs instead of filename sorting', () => {
+    const groups = buildSphinxNavigation([
+      doc('api/sample.alpha', 'Alpha', '', 'MODULE'),
+      doc('api/sample.zeta', 'Zeta', '', 'MODULE'),
+      doc(
+        'api/sample',
+        'Sample package',
+        '<div class="toctree-wrapper"><ul><li><a href="sample.zeta.html">Zeta</a></li><li><a href="sample.alpha.html">Alpha</a></li></ul></div>',
+        'MODULE'
+      ),
+    ]);
+
+    expect(groups).toEqual([
+      {
+        group: 'API Reference',
+        pages: [
+          { group: 'Sample package', pages: ['api/sample', 'api/sample.zeta', 'api/sample.alpha'] },
+        ],
+      },
+    ]);
+  });
+
+  it('falls back to the serialized toc when the body has no toctree wrapper', () => {
+    const groups = buildSphinxNavigation([
+      doc(
+        'index',
+        'Sample package',
+        '<h1>Sample package</h1>',
+        undefined,
+        '<ul><li><a href="#sample">Sample package</a><ul><li><a href="sample.html">Sample</a></li></ul></li></ul>'
+      ),
+      doc('sample', 'Sample module', '', 'MODULE'),
+    ]);
+
+    expect(groups).toEqual([
+      {
+        group: 'API Reference',
+        pages: [{ group: 'Sample package', pages: ['index', 'sample'] }],
+      },
+    ]);
+  });
+
+  it('resolves directory-style and HTML-style links when both candidate pages exist', () => {
+    expect(
+      buildSphinxNavigation([
+        doc(
+          'parent',
+          'Parent package',
+          '<div class="toctree-wrapper"><ul><li><a href="child/">Nested child</a></li><li><a href="child.html">Root child</a></li></ul></div>',
+          'MODULE'
+        ),
+        doc('parent/child', 'Nested child', '', 'MODULE'),
+        doc('child', 'Root child', '', 'MODULE'),
+      ])
+    ).toEqual([
+      {
+        group: 'API Reference',
+        pages: [{ group: 'Parent package', pages: ['parent', 'parent/child', 'child'] }],
+      },
+    ]);
+  });
+
+  it('falls back to dotted module and directory ancestry without a toctree', () => {
+    expect(
+      buildSphinxNavigation([
+        doc('api/sample', 'Sample package', '', 'MODULE'),
+        doc('api/sample.transport', 'Transport package', '', 'MODULE'),
+        doc('api/sample.transport.http', 'HTTP module', '', 'MODULE'),
+        doc('guides', 'Guides', '<p>Guides for the SDK.</p>'),
+        doc('guides/install', 'Installation', '<p>Install the SDK.</p>'),
+      ])
+    ).toEqual([
+      {
+        group: 'Getting Started',
+        pages: [{ group: 'Guides', pages: ['guides', 'guides/install'] }],
+      },
+      {
+        group: 'API Reference',
+        pages: [
+          {
+            group: 'Sample package',
+            pages: [
+              'api/sample',
+              {
+                group: 'Transport package',
+                pages: ['api/sample.transport', 'api/sample.transport.http'],
+              },
+            ],
+          },
+        ],
+      },
+    ]);
+  });
+
+  it('uses Sphinx parent metadata when hidden toctrees are absent from the body', () => {
+    expect(
+      buildSphinxNavigation([
+        doc('modules', 'Modules'),
+        {
+          ...doc('sample', 'Sample package', '', 'MODULE'),
+          parents: [{ link: '../modules/' }],
+        },
+        {
+          ...doc('client', 'Client module', '', 'MODULE'),
+          parents: [{ link: '../modules/' }, { link: '../sample/' }],
+        },
+      ])
+    ).toEqual([
+      {
+        group: 'API Reference',
+        pages: [
+          {
+            group: 'Modules',
+            pages: ['modules', { group: 'Sample package', pages: ['sample', 'client'] }],
+          },
+        ],
+      },
+    ]);
+  });
+
+  it('groups related module and path siblings without generating overview routes', () => {
+    const groups = buildSphinxNavigation([
+      doc('sample.transport.http', 'HTTP module', '', 'MODULE'),
+      doc('sample.transport.websocket', 'WebSocket module', '', 'MODULE'),
+      doc('sample.users', 'Users module', '', 'MODULE'),
+      doc('guides/install', 'Install', '<p>Install the SDK.</p>'),
+      doc('guides/quickstart', 'Quickstart', '<p>Create a client.</p>'),
+    ]);
+
+    expect(groups).toEqual([
+      {
+        group: 'Getting Started',
+        pages: [{ group: 'guides', pages: ['guides/install', 'guides/quickstart'] }],
+      },
+      {
+        group: 'API Reference',
+        pages: [
+          {
+            group: 'sample',
+            pages: [
+              {
+                group: 'sample.transport',
+                pages: ['sample.transport.http', 'sample.transport.websocket'],
+              },
+              'sample.users',
+            ],
+          },
+        ],
+      },
+    ]);
+    expect(pages(groups).sort()).toEqual([
+      'guides/install',
+      'guides/quickstart',
+      'sample.transport.http',
+      'sample.transport.websocket',
+      'sample.users',
+    ]);
+  });
+
+  it('preserves virtual API groups when a folder also contains a guide', () => {
+    const groups = buildSphinxNavigation([
+      doc('api/models', 'Models module', '', 'MODULE'),
+      doc('api/quickstart', 'Quickstart', '<p>Create a client.</p>'),
+      doc('api/client', 'Client module', '', 'MODULE'),
+    ]);
+
+    expect(groups).toEqual([
+      { group: 'Getting Started', pages: ['api/quickstart'] },
+      {
+        group: 'API Reference',
+        pages: [{ group: 'api', pages: ['api/client', 'api/models'] }],
+      },
+    ]);
+    expect(pages(groups).sort()).toEqual(['api/client', 'api/models', 'api/quickstart']);
+  });
+
+  it('traverses nested virtual folders separately for guides and modules', () => {
+    const groups = buildSphinxNavigation([
+      doc('api/client', 'Client module', '', 'MODULE'),
+      doc('api/models', 'Models module', '', 'MODULE'),
+      doc('api/guides/install', 'Install', '<p>Install the SDK.</p>'),
+      doc('api/guides/quickstart', 'Quickstart', '<p>Create a client.</p>'),
+    ]);
+
+    expect(groups).toEqual([
+      {
+        group: 'Getting Started',
+        pages: [{ group: 'guides', pages: ['api/guides/install', 'api/guides/quickstart'] }],
+      },
+      {
+        group: 'API Reference',
+        pages: [{ group: 'api', pages: ['api/client', 'api/models'] }],
+      },
+    ]);
+    expect(pages(groups).sort()).toEqual([
+      'api/client',
+      'api/guides/install',
+      'api/guides/quickstart',
+      'api/models',
+    ]);
+  });
+
+  it('avoids duplicates and cycles while keeping every generated page reachable', () => {
+    const groups = buildSphinxNavigation([
+      doc(
+        'index',
+        'Sample',
+        '<div class="toctree-wrapper"><ul><li><a href="sample.html">Sample</a></li><li><a href="sample.html">Duplicate</a></li><li><a href="missing.html">Missing</a></li><li><a href="sample.html#method">Method</a></li><li><a href="https://example.com/">External</a></li></ul></div>'
+      ),
+      doc(
+        'sample',
+        'Sample module',
+        '<div class="toctree-wrapper"><ul><li><a href="index.html">Index</a></li></ul></div>',
+        'MODULE'
+      ),
+      doc('orphan', 'Orphan module', '', 'MODULE'),
+    ]);
+
+    expect(pages(groups).sort()).toEqual(['index', 'orphan', 'sample']);
+    expect(groups.every((group) => group.group === 'API Reference')).toBe(true);
+  });
+
+  it('keeps legacy guide and module groups when no hierarchy is available', () => {
+    expect(
+      buildSphinxNavigation([
+        doc('index', 'Example SDK', '<p>Welcome to the SDK.</p>'),
+        doc('widgets', 'Widgets module', '', 'MODULE'),
+      ])
+    ).toEqual([
+      { group: 'Getting Started', pages: ['index'] },
+      { group: 'API Reference', pages: ['widgets'] },
+    ]);
+  });
+});

package/__test__/sdk-sphinx-signatures.test.ts

@@ -0,0 +1,148 @@
+import type { Element } from 'hast';
+import { describe, expect, it } from 'vitest';
+
+import { htmlToHast } from '../src/pipeline/root.js';
+import { renderSphinxLinkedCode, renderSphinxSignature } from '../src/sdk/sphinx-signatures.js';
+
+function signature(html: string): Element {
+  const element = htmlToHast(`<dt>${html}</dt>`).children.find((node) => node.type === 'element');
+  if (!element || element.type !== 'element') throw new Error('Missing signature element');
+  return element;
+}
+
+describe('renderSphinxSignature', () => {
+  it('preserves the Python signature and links parameter and return types', () => {
+    const content = renderSphinxSignature(
+      signature(
+        'create(<em class="sig-param"><span>body</span>: <a href="/models#example.Request">Request</a></em>) → <span class="sig-return-typehint"><a href="/models#example.Response">Response</a></span>'
+      )
+    );
+    expect(content).toContain('```python\ncreate(body: Request) → Response\n```');
+    expect(content).toContain(
+      '<ResponseField name={"body"} type={"Request"} typeHref={"/models#example.Request"} required>'
+    );
+    expect(content).toContain('**Returns:** <code>[Response](/models#example.Response)</code>');
+  });
+
+  it('links individual references within compound annotations and preserves default values', () => {
+    const content = renderSphinxSignature(
+      signature(
+        'create(<em class="sig-param">body: list[<a href="/models#example.Request">Request</a>] | None = None</em>)'
+      )
+    );
+    expect(content).toContain('create(body: list[Request] | None = None)');
+    expect(content).toContain('<ResponseField name={"body"} type={"list[Request] | None"}>');
+    expect(content).not.toContain('typeHref=');
+    expect(content).toContain(
+      '**Type:** <code>{"list["}[Request](/models#example.Request){"] | None"}</code>'
+    );
+  });
+
+  it('does not interpret equals signs in literals as defaults', () => {
+    const content = renderSphinxSignature(
+      signature('create(<em class="sig-param">operator: Literal["=", ":"]</em>)')
+    );
+    expect(content).toContain(`type={${JSON.stringify('Literal["=", ":"]')}} required>`);
+  });
+
+  it('marks typed variadic parameters optional and skips untyped separators', () => {
+    const content = renderSphinxSignature(
+      signature(
+        'create(<em class="sig-param">self</em>, <em class="sig-param">/</em>, <em class="sig-param">*args: str</em>, <em class="sig-param">**kwargs: object</em>)'
+      )
+    );
+    expect(content).toContain('<ResponseField name={"*args"} type={"str"}>');
+    expect(content).toContain('<ResponseField name={"**kwargs"} type={"object"}>');
+    expect(content).not.toContain('required');
+    expect(content).not.toContain('name={"self"}');
+  });
+
+  it('keeps malicious annotation text inert and drops unsafe hyperlinks', () => {
+    const content = renderSphinxSignature(
+      signature(
+        'create(<em class="sig-param">body: <a href="javascript:alert(1)">BadType</a></em>) → <span class="sig-return-typehint">{execute()} &lt;script&gt;unsafe&lt;/script&gt;</span>'
+      )
+    );
+    expect(content).not.toContain('javascript:');
+    expect(content).not.toContain('typeHref=');
+    expect(content).toContain('**Returns:** `{execute()} <script>unsafe</script>`');
+  });
+
+  it('encodes Markdown destination delimiters without changing the linked type text', () => {
+    const content = renderSphinxSignature(
+      signature(
+        'create() → <span class="sig-return-typehint"><a href="/models#Type)(payload)">Type</a></span>'
+      )
+    );
+    expect(content).toContain('[Type](/models#Type%29%28payload%29)');
+  });
+
+  it('uses a longer fence when a default value contains backticks', () => {
+    const content = renderSphinxSignature(
+      signature('create(<em class="sig-param">value: str = "```"</em>)')
+    );
+    expect(content).toContain('````python\ncreate(value: str = "```")\n````');
+  });
+
+  it('uses existing parameter and return type links without repeating generated details', () => {
+    const description = signature(
+      '<dl class="field-list simple"><dt>Parameters:</dt><dd><ul><li><p><strong>body</strong> (<a href="/models#example.Request"><em>example.Request</em></a>) – The request.</p></li><li><p><strong>options</strong> (<a href="/models#example.Options">Options</a>) – The options.</p></li></ul></dd><dt>Return type:</dt><dd><p><code><a href="/models#example.Response">Response</a></code></p></dd></dl>'
+    );
+    const content = renderSphinxSignature(
+      signature(
+        'create(<em class="sig-param">body: <a href="/models#example.Request">Request</a></em>, <em class="sig-param">options: <a href="/models#example.Options">Options</a></em>) → <span class="sig-return-typehint"><a href="/models#example.Response">Response</a></span>'
+      ),
+      description
+    );
+    expect(content).toContain('```python');
+    expect(content).not.toContain('<ResponseField');
+    expect(content).not.toContain('**Returns:**');
+  });
+
+  it('keeps fallback details for missing, unrelated, or unsafe documented links', () => {
+    const description = signature(
+      '<dl class="field-list"><dt>Parameters:</dt><dd><p><strong>body</strong> (<a href="javascript:alert(1)">Request</a>) – See <a href="/models#example.Request">Request</a>.</p></dd><dt>Return type:</dt><dd><p><a href="/models#example.OtherResponse">Response</a></p></dd></dl><dl class="py method"><dd><dl class="field-list"><dt>Parameters:</dt><dd><p><strong>body</strong> (<a href="/models#example.Request">Request</a>) – A nested method request.</p></dd></dl></dd></dl>'
+    );
+    const content = renderSphinxSignature(
+      signature(
+        'create(<em class="sig-param">body: <a href="/models#example.Request">Request</a></em>) → <span class="sig-return-typehint"><a href="/models#example.Response">Response</a></span>'
+      ),
+      description
+    );
+    expect(content).toContain('<ResponseField name={"body"}');
+    expect(content).toContain('typeHref={"/models#example.Request"}');
+    expect(content).toContain('**Returns:** <code>[Response](/models#example.Response)</code>');
+  });
+
+  it('does not repeat primitive types already documented in field lists', () => {
+    const content = renderSphinxSignature(
+      signature('get(<em class="sig-param">client_id: str</em>)'),
+      signature(
+        '<dl class="field-list"><dt>Parameters:</dt><dd><p><strong>client_id</strong> (<em>str</em>) – Identifier.</p></dd></dl>'
+      )
+    );
+    expect(content).not.toContain('<ResponseField');
+  });
+});
+
+describe('renderSphinxLinkedCode', () => {
+  it('preserves legacy field-list references nested inside inline code', () => {
+    const content = renderSphinxLinkedCode(
+      signature(
+        '<code class="xref py py-class">list[<a href="/models#example.Request"><span class="pre">Request</span></a>] | None</code>'
+      )
+    );
+    expect(content).toBe('<code>{"list["}[Request](/models#example.Request){"] | None"}</code>');
+  });
+
+  it('leaves unlinked code to the normal conversion pipeline', () => {
+    expect(renderSphinxLinkedCode(signature('<code>str | None</code>'))).toBeUndefined();
+  });
+
+  it('keeps surrounding expression-like text inert', () => {
+    const content = renderSphinxLinkedCode(
+      signature('<code>{execute()} | <a href="/models#example.Request">Request</a></code>')
+    );
+    expect(content).toBe('<code>{"{execute()} | "}[Request](/models#example.Request)</code>');
+  });
+});