mirror of
https://github.com/mintlify/docs.git
synced 2026-09-14 13:35:46 +08:00
Ethan Palm
118 lines
4.6 KiB
Plaintext
118 lines
4.6 KiB
Plaintext
---
|
|
title: "Generate SDK reference pages from doc-tool output"
|
|
sidebarTitle: "SDK reference setup"
|
|
description: "Publish SDK reference documentation in Mintlify from TypeDoc, DocFX, Javadoc, Sphinx, or phpDocumentor artifacts using the sdk navigation property."
|
|
keywords: ["sdk", "typedoc", "docfx", "javadoc", "sphinx", "phpdocumentor", "reference"]
|
|
---
|
|
|
|
Use the `sdk` navigation property to generate reference pages for your SDK libraries from the documentation tools you already run. Mintlify reads each tool's build artifact and creates a page for every class, interface, module, and function, with navigation groups, cross-page links, and search indexing included.
|
|
|
|
## Supported formats
|
|
|
|
| `format` | Tool | Artifact |
|
|
| --- | --- | --- |
|
|
| `typedoc` | [TypeDoc](https://typedoc.org) (TypeScript/JavaScript) | JSON export file |
|
|
| `docfx` | [DocFX](https://dotnet.github.io/docfx/) (.NET) | `docfx metadata` output directory (ManagedReference YAML) |
|
|
| `javadoc` | [Javadoc](https://docs.oracle.com/en/java/javase/17/javadoc/javadoc.html) (Java) | Standard doclet HTML directory |
|
|
| `sphinx` | [Sphinx](https://www.sphinx-doc.org) (Python) | JSON builder output directory |
|
|
| `phpdoc` | [phpDocumentor](https://phpdoc.org) (PHP) | `structure.xml` file |
|
|
|
|
## Generate an artifact
|
|
|
|
Run your documentation tool with a machine-readable output format. If you already publish generated docs from CI, this is usually a one-flag change to the same command.
|
|
|
|
<CodeGroup>
|
|
|
|
```bash TypeDoc
|
|
npx typedoc --json typedoc.json src/index.ts
|
|
```
|
|
|
|
```bash DocFX
|
|
docfx metadata docfx.json
|
|
```
|
|
|
|
```bash Javadoc
|
|
javadoc -d javadoc-output -sourcepath src/main/java -subpackages com.example
|
|
# Or download the published javadoc jar from Maven Central
|
|
```
|
|
|
|
```bash Sphinx
|
|
python -m sphinx -b json docs/source artifacts/json
|
|
```
|
|
|
|
```bash phpDocumentor
|
|
phpdoc -d src -t artifacts --template=xml
|
|
```
|
|
|
|
</CodeGroup>
|
|
|
|
## Auto-populate SDK pages
|
|
|
|
Add an `sdk` property to a tab in your `docs.json`. Mintlify parses the artifact and creates navigation groups and pages for the library.
|
|
|
|
```json
|
|
"navigation": {
|
|
"tabs": [
|
|
{
|
|
"tab": "SDK Reference",
|
|
"sdk": {
|
|
"format": "typedoc",
|
|
"source": "sdk-artifacts/typedoc.json",
|
|
"directory": "sdk/typescript"
|
|
}
|
|
}
|
|
]
|
|
}
|
|
```
|
|
|
|
<Note>
|
|
You must declare `sdk` on a [tab](/organize/navigation#tabs). A tab with `sdk` may include `groups`, but no other navigation structures, such as `pages`, `versions`, or `languages`. It also cannot include an `openapi`, `asyncapi`, or `graphql` property.
|
|
</Note>
|
|
|
|
<ParamField path="format" type="string" required>
|
|
The documentation tool that produced the artifact: `typedoc`, `docfx`, `javadoc`, `sphinx`, or `phpdoc`.
|
|
</ParamField>
|
|
|
|
<ParamField path="source" type="string" required>
|
|
Relative path to the artifact file or directory in your docs repository, or an HTTPS URL. Does not accept HTTP URLs.
|
|
</ParamField>
|
|
|
|
<ParamField path="directory" type="string">
|
|
The URL path prefix for generated pages. Defaults to `sdk-reference`.
|
|
</ParamField>
|
|
|
|
Add multiple tabs to document multiple libraries. Use a unique `directory` for each library to avoid route collisions.
|
|
|
|
<Tip>
|
|
Add your artifact directory to [`.mintignore`](/organize/mintignore) so Mintlify treats artifacts as build inputs rather than publishing them as static assets.
|
|
</Tip>
|
|
|
|
## Generated pages
|
|
|
|
Mintlify adds the generated navigation groups after any `groups` on the tab. The groups vary by format and may represent modules, packages, namespaces, or symbol types.
|
|
|
|
Each generated page documents a class, interface, function, type, or other symbol from the artifact and links to related generated pages. If a converter produces pages that do not belong to a group, Mintlify collects them under a `Reference` group.
|
|
|
|
## Use remote sources
|
|
|
|
Set `source` to an HTTPS URL to fetch the artifact at build time instead of committing it to your docs repository.
|
|
|
|
Single-file formats (`typedoc`, `phpdoc`) accept a direct file URL. Directory formats (`docfx`, `javadoc`, `sphinx`) accept a zip archive. Javadoc jars published to Maven Central work without repackaging:
|
|
|
|
```json
|
|
{
|
|
"tab": "Java SDK",
|
|
"sdk": {
|
|
"format": "javadoc",
|
|
"source": "https://repo1.maven.org/maven2/com/example/my-library/1.0.0/my-library-1.0.0-javadoc.jar",
|
|
"directory": "sdk/java"
|
|
}
|
|
}
|
|
```
|
|
|
|
Remote artifacts have a 50 MB download limit and a 200 MB extracted size limit.
|
|
|
|
## Keep references up to date
|
|
|
|
Regenerate the artifact whenever your SDK changes. A common pattern is a CI job in each SDK repository that runs the documentation tool on release. The job either commits the artifact to your docs repository or uploads it to a stable URL that `source` points to.
|