{"schemaVersion":1,"title":"Explore 20 native SDK samples","url":"https://appgram.github.io/docsy/guides/ingestion/sdk-samples","markdownUrl":"https://appgram.github.io/docsy/format-md/guides/ingestion/sdk-samples","jsonUrl":"https://appgram.github.io/docsy/agent/pages/guides/ingestion/sdk-samples.json","version":"current","locale":"en","markdown":"# Explore 20 native SDK samples\n\nInspect actual generator output, source fixtures, tool versions, reproduction commands, and provenance hashes.\n\nWritten by: [nedimf](https://github.com/nedimf), [AppGram](https://appgram.dev)\n\nThe portal now imports actual documentation-generator artifacts for **20 source languages**, rather than relabeling manually prepared compact JSON as native support. Every sample was generated from source code in `tests/generators/input/`.\n\n## Native samples\n\n| Language / reference | Native adapter | What to inspect in this sample |\n| --- | --- | --- |\n| [Swift](/swift-sdk) | `docc` | Struct, property, enum cases, default arguments, throwing method, 3 examples |\n| [Dart](/dart-sdk) | `dartdoc` | Class, property, enum values, named optional argument, 3 examples |\n| [TypeScript](/typescript-sdk) | `typedoc` | Class, interface, properties, enum, optional/default arguments, remarks, deprecation, errors, 4 examples |\n| [JavaScript](/javascript-sdk) | `jsdoc` | Class, property, optional arguments, deprecation, typed errors, 4 examples |\n| [Python](/python-sdk) | `sphinx` | Class, attribute, typed lists, optional arguments, return prose, raised exception, 4 examples |\n| [Rust](/rust-sdk) | `rustdoc` | Struct field, enum variant, slices, `Result` error contract, 4 examples |\n| [C#](/dotnet-sdk) | `docfx` | Class, property, enum values, arrays, remarks, exceptions, 3 examples |\n| [F#](/fsharp-sdk) | `docfx` | Class, property, arrays, exceptions, 3 F# examples; declarations use DocFX's C# fallback |\n| [Visual Basic](/visualbasic-sdk) | `docfx` | Class, property, arrays, exceptions, native VB declarations, 3 examples |\n| [Kotlin](/kotlin-sdk) | `dokka` | Class, property, enum values, default arguments, typed throws, 3 examples |\n| [Java](/java-sdk) | `javadoc` | Class, field, enum constants, arrays, deprecation, throws, 3 examples |\n| [Scala](/scala-sdk) | `scaladoc` | Class, property, typed lists, default argument, return prose, throws, 4 examples |\n| [Go](/go-sdk) | `godoc` | Struct fields, interface declaration, receiver methods, slices, 3 usage blocks |\n| [C](/c-sdk) | `doxygen` | Struct fields, enum values, pointer arguments, documented status return, 2 examples |\n| [C++](/cpp-sdk) | `doxygen` | Class, property, pointer arguments, return prose, exceptions, 3 examples |\n| [Objective-C](/objectivec-sdk) | `doxygen` | Class, property, multi-part selectors, pointer arguments, return prose, 3 examples |\n| [PHP](/php-sdk) | `phpdoc` | Class, property, default arguments, arrays, exceptions, 3 examples |\n| [Ruby](/ruby-sdk) | `yard` | Class, attribute, typed parameters, default argument, raised exception, 3 examples |\n| [Elixir](/elixir-sdk) | `exdoc` | Module documentation, typed list functions, validation prose, 4 `iex` examples |\n| [Lua](/lua-sdk) | `ldoc` | Functions, typed tables, optional argument, return documentation, raised error, 3 usage examples |\n\nThese are small teaching libraries, not published SDK packages. Their source implements a greeting API so you can compare the same concepts across generators. The method signatures, parameters, return types, and descriptions on the native pages are imported from generator output, not authored in the site YAML.\n\n## Read a richer reference\n\nEvery language now includes a batch operation as well as the single-reader method. Open **In this reference → examples** to jump directly to imported usage code. The counts are computed from the imported symbols, not hard-coded per language.\n\n* **Examples** come from native documentation comments: TypeDoc/JSDoc `@example`, Python literal blocks, Javadoc `<pre>`, KDoc Markdown, Scaladoc code blocks, Swift DocC code listings, rustdoc fences, compiler XML `<example>`, Doxygen `@code`, phpDocumentor `@example`, YARD `@example`, ExDoc `iex` blocks, and LDoc `@usage`.\n* **Parameters and returns** preserve types and descriptions where the generator supplies them. Optional/default parameters are marked when exposed by the input. Properties, enum values, remarks, deprecations, and error contracts are shown when imported; unsupported or absent metadata is not invented.\n* **Errors** are separate from usage examples. Dart and Elixir's validation behavior remains in native prose in these fixtures. Go does not have exceptions; the C sample documents status codes in its return description. These are not falsely labeled as structured thrown exceptions.\n* **Examples are library usage**, not automatically generated HTTP requests. The [OpenAPI example](/api/posts) has its own language selector for request code.\n\nThe samples demonstrate supported content, not every feature of every language's documentation generator. Native annotations, inter-package links, source browsing, tutorials, and complex type layouts are not all reproduced. Go's usage blocks come from source comments in `go doc -all`; this importer does not discover `Example*` test functions. Example code is displayed as documentation, not executed by the Docsy renderer.\n\n## Verify the provenance\n\n`sources/native/provenance.json` records all 20 languages, generator versions, exact input and output files, SHA-256 hashes, and reproduction commands. `npm test` verifies those hashes and imports each native artifact. Changing fixture source without regenerating the output fails the provenance test.\n\nThe recorded tools are TypeDoc, JSDoc, Sphinx, Javadoc, Dokka, Scaladoc, DocFX, Doxygen, Go's standard documentation tool, stable rustdoc, Swift DocC, Dartdoc, phpDocumentor, YARD, ExDoc, and LDoc. A single native format can serve several languages: Doxygen covers C/C++/Objective-C, and DocFX imports the C#/F#/VB compiler assemblies and XML comments.\n\nOnly original reference artifacts are retained. Generator CSS, JavaScript, fonts, compiler binaries, and caches are excluded. The importers parse data; they do not embed or execute the upstream documentation site.\n\n## Configure a native source\n\n```yaml\ningestion:\n  sdks:\n    - id: python\n      slug: python-sdk\n      adapter: sphinx\n      source: sources/native/python\n      name: Python library\n      language: python\n      install: ''\n      overview: Reference imported from Sphinx JSON output.\n      icon: assets/sdks/python.svg\n      maxFiles: 10000\n      maxFileBytes: 10485760\n      maxTotalBytes: 104857600\n```\n\nChange `adapter`, `source`, and `language` to choose an input. A source may be the generator's individual artifact file or a directory of native artifacts. The exact expected format is documented in **SDK adapters**. Native SDK inputs are local files; URL downloads and archive extraction are deliberately not performed by the renderer.\n\nBranding stays configurable: `icon` is the local SVG for the overview card and reference heading. Add `iconDark: assets/my-language-dark.svg` when a mark needs a light variant on dark backgrounds. The portal vendors all 20 language marks locally; it does not load an icon font or a tracking/CDN asset. Replacing an icon does not change ingestion.\n\nVersion-specific inputs still use `versions: { preview: sources/preview/python }`. Add the registered `slug` to navigation as usual. Search, Markdown, agent JSON, locale routing, and access rules use the same normalized reference model. Native descriptions retain their generator's language; selecting a locale does not automatically translate upstream API text.\n\n## Regenerate the real fixtures\n\nInstall Docsy's npm development dependencies, then build the isolated Linux generator image:\n\n```bash\nnpm ci\nnpm run fixtures:image\nnpm run fixtures:generate\nnpm test\nnpm run validate\nnpm run build\n```\n\nRun these commands from a repository checkout. The full reproduction run also needs Python, a JDK, Go, stable Rust, Ruby, Dart, and the Swift compiler/DocC tool. It downloads documentation-tool dependencies into the ignored `.docsy/generators/` cache. Docker supplies Doxygen, DocFX, phpDocumentor, LDoc, and ExDoc. Toolchains are needed to regenerate fixtures, **not** to import their checked-in output or build Docsy.\n\nUse `npm run fixtures:generate -- --only python,java` for a subset. Host paths can be selected with `DOCSY_JAVA_HOME`, `DOCSY_PYTHON`, `DOCSY_DART`, `DOCSY_RUBY`, and `DOCSY_DOCC`. The full Swift generation step uses a standalone source file and CLI tools; it never invokes `xcodebuild` or builds an Xcode project. The reproduction script currently targets macOS/Linux hosts; Windows users can consume the generated artifacts without running this script.\n\n## Know the format boundaries\n\n* **F#:** DocFX is run against an actual compiled F# assembly and compiler XML comments. When DocFX supplies C# declarations instead of F# syntax, the code block is labeled C#, not disguised as F#.\n* **Scala:** this adapter is tested against Scaladoc 2 HTML, not Scala 3's different output.\n* **Rust:** the importer reads stable rustdoc HTML; it does not depend on the unstable nightly JSON schema. Generator-provided inherited methods may appear.\n* **HTML formats:** selectors are tested against the recorded generator versions. Custom themes or incompatible generator versions can need an adapter update. The reference is normalized, not a pixel-identical copy of the original documentation.\n* **Cross-references:** basic native inheritance/conformance references are retained where available. This is not a full reproduction of every upstream generator feature, source browser, or inter-package link resolver.\n\n## Keep portable metadata separate\n\n[Portable metadata](/compact-sdk) remains available for custom pipelines. That page and the legacy converter regression fixtures are explicitly hand-authored examples. They are **not counted** as native-language coverage. The Swift `swift-symbols` adapter for AppGram/docc2json remains supported alongside the direct `docc` importer.\n\nFor HTTP requests rather than library symbols, open [Posts](/api/posts) and use the request-language selector. Those snippets are generated from OpenAPI; they are not native library-documentation imports.\n\n","contentLocale":"en","isFallback":false,"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-samples.md"}