{"schemaVersion":1,"title":"Ingest SDK documentation","url":"https://appgram.github.io/docsy/versions/current/es/guides/ingestion/sdk-adapters","markdownUrl":"https://appgram.github.io/docsy/format-md/versions/current/es/guides/ingestion/sdk-adapters","jsonUrl":"https://appgram.github.io/docsy/agent/pages/versions/current/es/guides/ingestion/sdk-adapters.json","version":"current","locale":"es","markdown":"# Ingest SDK documentation\n\nImport 16 native generator formats covering 20 source languages into consistent SDK reference pages.\n\nWritten by: [nedimf](https://github.com/nedimf), [AppGram](https://appgram.dev)\n\nDocsy can render SDK reference pages from documentation metadata produced by several language ecosystems. Each adapter converts its source into one normalized category-and-symbol model, so the default interface stays consistent across SDKs.\n\n## Supported adapters\n\n| Adapter | Intended input |\n| --- | --- |\n| `typedoc` | TypeDoc project JSON, including nested modules/members, signatures, parameters, examples, enums, and properties |\n| `jsdoc` | JSDoc `-X` doclet JSON for JavaScript |\n| `sphinx` | Sphinx JSON-builder directory containing `.fjson` API definitions |\n| `javadoc` | Standard Javadoc HTML directory |\n| `dokka` | Dokka HTML directory for Kotlin |\n| `scaladoc` | Scaladoc 2 HTML directory |\n| `docfx` | ManagedReference YAML from C#/F#/VB assemblies and compiler XML comments |\n| `doxygen` | Doxygen XML directory, tested with C, C++, and Objective-C |\n| `godoc` | Plain-text output from `go doc -all` |\n| `rustdoc` | Stable rustdoc HTML directory, not nightly JSON |\n| `docc` | Swift DocC archive/data directory containing render-node JSON |\n| `phpdoc` | phpDocumentor XML `structure.xml` |\n| `yard` | YARD HTML directory for Ruby |\n| `exdoc` | ExDoc HTML directory for Elixir |\n| `ldoc` | LDoc HTML directory for Lua |\n| `typedoc-lite` | Docsy's compact `modules` + `navigation` JSON; declarations, parameters, properties, methods, enum values, and examples |\n| `swift-symbols` | [AppGram/docc2json](https://github.com/AppGram/docc2json) output: Swift types, protocols, enums, and navigation |\n| `dartdoc` | Native Dartdoc HTML directory with signatures and members; legacy flat JSON index remains supported |\n\nSDK sources are local, project-relative files or artifact directories. Unlike the OpenAPI loader, SDK adapters do not fetch HTTPS URLs or extract archives. Generate or download artifacts into your repository before building. Keep private inputs outside `public/`. Generators are never executed as a side effect of reading YAML or building Docsy.\n\n> Native coverage is tested against real generator output\n>\n> The portal's native samples cover 20 source languages across 16 native formats. The original generator outputs, source code, tool versions, commands, and hashes are committed under `sources/native/` and `tests/generators/`. The separate compact format is still useful, but does not count as native language support. Pdoc and raw C# compiler XML alone are not direct adapters; use Sphinx or DocFX artifacts respectively.\n\nThe **Native SDK samples** section contains the generated reference pages. See **Explore SDK samples** for reproduction commands and format-specific limitations.\n\n## Register an SDK\n\nAdd an entry to `ingestion.sdks`:\n\n```yaml\ningestion:\n  sdks:\n    - id: javascript\n      slug: javascript-sdk\n      adapter: typedoc\n      source: sources/javascript/docs.json\n      name: JavaScript SDK\n      language: typescript\n      install: npm install @acme/sdk\n      installLanguage: bash\n      overview: Typed client for the Acme API.\n      icon: assets/sdks/javascript.svg\n      quickstart:\n        language: typescript\n        code: |\n          import { createClient } from '@acme/sdk';\n          const client = createClient();\n```\n\nThe SDK is rendered at `/javascript-sdk` beneath `site.basePath`.\n\n## Add it to navigation\n\nRoutes and navigation are intentionally separate. Register the route under `ingestion.sdks`, then place it where readers should find it:\n\n```yaml\nnavigation:\n  - title: SDKs\n    items:\n      - title: JavaScript\n        href: /javascript-sdk\n        icon: assets/sdks/javascript.svg\n```\n\nThe page automatically participates in full-text search, the overview catalog, Markdown export, and agent JSON. `quickstart` is authored in YAML, not extracted from the SDK source. Its language defaults to the SDK's `language`; `installLanguage` controls the install block. Neither block is executed during ingestion.\n\nNative examples are different: the importer reads code blocks from generator comments/artifacts and places them beside their symbol declarations. Remarks, optional arguments, enum values, properties, deprecations, and documented errors are retained where the adapter exposes them. [Explore the richer 20-language samples](/guides/ingestion/sdk-samples) for the exact content of each fixture and remaining limitations. `icon` and optional `iconDark` choose local SVG branding for both SDK cards and reference headings; they do not affect ingestion.\n\n## Use the compact TypeDoc format\n\nThe `typedoc-lite` adapter accepts a small JSON document when standard TypeDoc output is unnecessary:\n\n```json\n{\n  \"modules\": [\n    {\n      \"name\": \"AcmeSDK\",\n      \"types\": [\n        {\n          \"name\": \"createClient\",\n          \"kind\": \"function\",\n          \"declaration\": \"declare function createClient(baseUrl: string): Client;\",\n          \"parameters\": [{ \"name\": \"baseUrl\", \"type\": \"string\" }],\n          \"returnType\": \"Client\",\n          \"description\": {\n            \"summary\": \"Create a configured API client.\",\n            \"example\": \"const client = createClient('https://api.example.com');\"\n          }\n        }\n      ]\n    }\n  ],\n  \"navigation\": {\n    \"categories\": [{ \"title\": \"Functions\", \"items\": [\"createClient\"] }]\n  }\n}\n```\n\nUse standard TypeDoc when the upstream tool already produces complete metadata. Use the compact format when another build process or coding agent is creating the source deliberately.\n\nThe compact adapter currently reads the first module. Category `items` must reference names from that module's `types`. Set `language: python`, `rust`, `csharp`, or `kotlin` in YAML to render declarations and examples in another language without changing the compact schema.\n\n## Swift through AppGram/docc2json\n\nSwift documentation is supported through [AppGram/docc2json](https://github.com/AppGram/docc2json). The converter reads an existing DocC archive or processed `docs/data` folder and produces the JSON schema consumed by Docsy's `swift-symbols` adapter.\n\n```text\nExisting DocC archive → AppGram/docc2json → SDK JSON → Docsy swift-symbols\n```\n\nWith the converter installed, use an archive you have already generated:\n\n```bash\ndocc2json --input ./AtlasSDK.doccarchive \\\n  --output ./sources/atlas-swift.json \\\n  --public-only\n```\n\nAlternatively, pass `--input ./docs/data` for a processed DocC data folder. Then register its output:\n\n```yaml\ningestion:\n  sdks:\n    - id: swift\n      slug: swift-sdk\n      adapter: swift-symbols\n      source: sources/atlas-swift.json\n      name: Atlas Swift SDK\n      language: swift\n      install: '.package(path: \"../AtlasSDK\")'\n      installLanguage: swift\n      overview: Swift API reference generated with AppGram/docc2json.\n```\n\nThe adapter reads the first module's `types`, `protocols`, and `enums`, with category item names in `navigation.categories`. Descriptions use `abstract`, examples use `examples[].code`, and method parameters live under `signature.parameters`. Protocol method requirements use `requirements` with `kind: func` or `method`; their async flag comes from `signature.async`.\n\nDocsy consumes the generated JSON; it does not run the Swift documentation build or the converter for you. Raw `.symbols.json` and `.doccarchive` paths are not direct inputs to `swift-symbols`—the supported converter bridges those formats. You can build the portal from checked-in converter output without Xcode.\n\nThe portal's Swift page now uses actual DocC render-node output through the direct `docc` adapter. The older `swift-symbols` regression fixture remains a hand-authored schema fixture and is not counted as native coverage. That converter adapter still renders a subset of docc2json output; module articles, extensions, associated types, and conformance relationships are not fully imported into its SDK view.\n\n## Dart metadata\n\nPoint `adapter: dartdoc` at the directory generated by `dart doc` to import native HTML signatures and member descriptions. The legacy JSON-array input with `name`, `qualifiedName`, numeric `kind`, and `desc` is also accepted; that compact index only reads kinds `3` (class), `5` (enum), and `8` (extension) and does not contain complete method details.\n\nThe native TypeDoc reader now walks nested modules and members, preserving signatures, parameter types, returns, examples, properties, enum values, and overload declarations. Complex upstream features and custom themes are not a guarantee of complete semantic parity. The exact tested versions and known boundaries are in **Explore SDK samples**.\n\n## Bound native input sizes\n\nEvery SDK entry accepts `maxFiles` (default 10,000), `maxFileBytes` (default 10 MiB), and `maxTotalBytes` (default 100 MiB). Directory walks and file sizes are bounded. Symlinks and XML entities/DOCTYPE declarations are rejected. The loader does not execute artifact scripts, Python pickle files, or Ruby Marshal databases.\n\nF# DocFX import uses actual compiled F# APIs. If the artifact supplies only C# syntax, its declaration is labeled C#. Scala support here targets Scaladoc 2 HTML; Rust support targets stable rustdoc HTML. HTML adapter selectors depend on the generator format, so custom themes and new incompatible versions may require an adapter update.\n\n## Protect private SDK reference\n\nSDK pages use the same ordered lock-mode rules as articles and API pages:\n\n```yaml\naccess:\n  mode: locked\n  rules:\n    - pattern: /javascript-sdk\n      tiers: [developer, enterprise]\n```\n\nKeep protected source JSON outside `public/`. Static files under `public/` bypass request-time authorization.\n\n","contentLocale":"en","isFallback":true,"authorship":{"authors":[{"name":"nedimf","kind":"human","github":"nedimf","avatar":"/docsy/assets/authors/nedimf.png","role":"AppGram","id":"nedimf","url":"https://github.com/nedimf"},{"name":"AppGram","kind":"organization","github":"AppGram","url":"https://appgram.dev","avatar":"/docsy/assets/ag-logo.svg","id":"appgram"}],"contributors":[],"reviewedBy":[]},"editUrl":"https://github.com/AppGram/docsy/edit/main/content/ingestion/sdk-adapters.md"}