diff --git a/api-playground/sdk-setup.mdx b/api-playground/sdk-setup.mdx new file mode 100644 index 000000000..4241c988a --- /dev/null +++ b/api-playground/sdk-setup.mdx @@ -0,0 +1,116 @@ +--- +title: "SDK reference setup" +description: "Generate SDK reference pages from TypeDoc, DocFX, Javadoc, Sphinx, or phpDocumentor artifacts, so all your language SDK docs live inside your Mintlify site." +keywords: ["sdk", "typedoc", "docfx", "javadoc", "sphinx", "phpdoc"] +--- + +Use the `sdk` navigation property to publish SDK reference pages from artifacts produced by common documentation generators. Mintlify reads the artifact at build time and expands the tab into a set of generated MDX pages with grouped navigation. + +## Supported formats + +| Format | Generator | Expected artifact | +| -------- | ----------------- | ------------------------------------------ | +| `typedoc` | [TypeDoc](https://typedoc.org/) | JSON export (`typedoc --json out.json`) | +| `docfx` | [DocFX](https://dotnet.github.io/docfx/) | `ManagedReference` YAML output directory | +| `javadoc` | [Javadoc](https://docs.oracle.com/javase/8/docs/technotes/tools/windows/javadoc.html) | Standard doclet HTML output directory (or `.jar`) | +| `sphinx` | [Sphinx](https://www.sphinx-doc.org/) | JSON builder output (`sphinx-build -b json`) | +| `phpdoc` | [phpDocumentor](https://www.phpdoc.org/) | `structure.xml` file | + +## Add an SDK reference + +Add an `sdk` property to a [tab](/organize/navigation#tabs) in your `docs.json`. Mintlify generates one page per class, module, function, or type in the artifact, organized into groups. + + + +```json Local directory +"navigation": { + "tabs": [ + { + "tab": "SPA JS", + "sdk": { + "format": "typedoc", + "source": "sdk-artifacts/spa-js/typedoc.json" + } + } + ] +} +``` + +```json Remote URL +"navigation": { + "tabs": [ + { + "tab": "Java SDK", + "sdk": { + "format": "javadoc", + "source": "https://repo1.maven.org/maven2/com/example/sdk/1.0.0/sdk-1.0.0-javadoc.jar" + } + } + ] +} +``` + +```json Custom directory +"navigation": { + "tabs": [ + { + "tab": "SPA JS", + "sdk": { + "format": "typedoc", + "source": "sdk-artifacts/spa-js/typedoc.json", + "directory": "libraries/auth0-spa-js" + } + } + ] +} +``` + + + + + You must declare `sdk` on a tab. 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. + + + + The documentation generator that produced the artifact. One of `typedoc`, `docfx`, `javadoc`, `sphinx`, or `phpdoc`. + + + + A local path to the artifact in your documentation repository or an HTTPS URL to a hosted artifact. Does not accept HTTP URLs. + + For single-file formats (`typedoc`, `phpdoc`), point to the file. For directory-shaped formats (`docfx`, `javadoc`, `sphinx`), point to the directory locally, or to a `.zip` or `.jar` archive when remote. + + + + The directory to store generated pages under. Defaults to `sdk-reference`. + + +## Exclude artifacts from your build + +Add your artifact directory to [`.mintignore`](/organize/mintignore) so raw generator output is treated as a build input, not published as static files: + +```text .mintignore +sdk-artifacts/ +``` + +## Remote sources + +When `source` is an HTTPS URL, Mintlify fetches the artifact at build time. For directory-shaped formats, use a `.zip` archive; for Javadoc, a `.jar` from a package registry like Maven Central also works. + +Remote artifacts are capped at 50 MB compressed and 200 MB extracted, follow a 30-second timeout, and are protected against redirects to private addresses and against zip-slip during extraction. + +## Generated pages + +Each converter produces: + +- Grouped navigation (for example, by module, package, or namespace) that Mintlify appends to the tab's `groups`. +- One MDX page per class, function, type, or member documented in the artifact. +- Cross-links between generated pages, so readers can navigate between related types. + +If the artifact contains items that don't belong to any group, Mintlify collects them under a `Reference` group. + +You can add your own hand-written `groups` to the same tab. They render alongside the generated groups. + +## Update your documentation + +Mintlify regenerates SDK reference pages when you run `mint dev` or when you push changes to your documentation repository. If the artifact is hosted at an HTTPS URL, updates to the artifact regenerate on the next build. diff --git a/docs.json b/docs.json index c16d6887c..55ca6d189 100644 --- a/docs.json +++ b/docs.json @@ -178,6 +178,7 @@ "api-playground/mdx-setup", "api-playground/asyncapi-setup", "api-playground/graphql-setup", + "api-playground/sdk-setup", "api-playground/troubleshooting" ] }, diff --git a/es.json b/es.json index 47e0a1749..b46a30b37 100644 --- a/es.json +++ b/es.json @@ -157,6 +157,7 @@ "es/api-playground/mdx-setup", "es/api-playground/asyncapi-setup", "es/api-playground/graphql-setup", + "es/api-playground/sdk-setup", "es/api-playground/troubleshooting" ] }, diff --git a/es/api-playground/sdk-setup.mdx b/es/api-playground/sdk-setup.mdx new file mode 100644 index 000000000..adfef8d7b --- /dev/null +++ b/es/api-playground/sdk-setup.mdx @@ -0,0 +1,128 @@ +--- +title: "Configuración de referencia del SDK" +description: "Genera páginas de referencia del SDK a partir de artefactos de TypeDoc, DocFX, Javadoc, Sphinx o phpDocumentor, para que toda la documentación de tus SDK por lenguaje viva dentro de tu sitio de Mintlify." +keywords: ["sdk", "typedoc", "docfx", "javadoc", "sphinx", "phpdoc"] +--- + +Usa la propiedad de navegación `sdk` para publicar páginas de referencia del SDK a partir de artefactos generados por los generadores de documentación más comunes. Mintlify lee el artefacto en tiempo de compilación y expande la pestaña en un conjunto de páginas MDX generadas con navegación agrupada. + +
+ ## Formatos compatibles +
+ +| Formato | Generador | Artefacto esperado | +| -------- | ----------------- | ------------------------------------------ | +| `typedoc` | [TypeDoc](https://typedoc.org/) | Exportación JSON (`typedoc --json out.json`) | +| `docfx` | [DocFX](https://dotnet.github.io/docfx/) | Directorio de salida YAML `ManagedReference` | +| `javadoc` | [Javadoc](https://docs.oracle.com/javase/8/docs/technotes/tools/windows/javadoc.html) | Directorio de salida HTML del doclet estándar (o `.jar`) | +| `sphinx` | [Sphinx](https://www.sphinx-doc.org/) | Salida del builder JSON (`sphinx-build -b json`) | +| `phpdoc` | [phpDocumentor](https://www.phpdoc.org/) | Archivo `structure.xml` | + +
+ ## Agrega una referencia de SDK +
+ +Añade una propiedad `sdk` a una [pestaña](/es/organize/navigation#tabs) en tu `docs.json`. Mintlify genera una página por cada clase, módulo, función o tipo del artefacto, organizadas en grupos. + + + +```json Local directory +"navigation": { + "tabs": [ + { + "tab": "SPA JS", + "sdk": { + "format": "typedoc", + "source": "sdk-artifacts/spa-js/typedoc.json" + } + } + ] +} +``` + +```json Remote URL +"navigation": { + "tabs": [ + { + "tab": "Java SDK", + "sdk": { + "format": "javadoc", + "source": "https://repo1.maven.org/maven2/com/example/sdk/1.0.0/sdk-1.0.0-javadoc.jar" + } + } + ] +} +``` + +```json Custom directory +"navigation": { + "tabs": [ + { + "tab": "SPA JS", + "sdk": { + "format": "typedoc", + "source": "sdk-artifacts/spa-js/typedoc.json", + "directory": "libraries/auth0-spa-js" + } + } + ] +} +``` + + + + + Debes declarar `sdk` en una pestaña. Una pestaña con `sdk` puede incluir `groups`, pero ninguna otra estructura de navegación, como `pages`, `versions` o `languages`. Tampoco puede incluir una propiedad `openapi`, `asyncapi` o `graphql`. + + + + El generador de documentación que produjo el artefacto. Uno de `typedoc`, `docfx`, `javadoc`, `sphinx` o `phpdoc`. + + + + Una ruta local al artefacto en tu repositorio de documentación o una URL HTTPS a un artefacto alojado. No se aceptan URL HTTP. + + Para formatos de un solo archivo (`typedoc`, `phpdoc`), apunta al archivo. Para formatos con estructura de directorio (`docfx`, `javadoc`, `sphinx`), apunta al directorio localmente, o a un archivo `.zip` o `.jar` cuando sea remoto. + + + + El directorio bajo el cual se almacenan las páginas generadas. El valor predeterminado es `sdk-reference`. + + +
+ ## Excluye los artefactos de tu compilación +
+ +Agrega el directorio de tu artefacto a [`.mintignore`](/es/organize/mintignore) para que la salida sin procesar del generador se trate como una entrada de la compilación y no se publique como archivos estáticos: + +```text .mintignore +sdk-artifacts/ +``` + +
+ ## Fuentes remotas +
+ +Cuando `source` es una URL HTTPS, Mintlify obtiene el artefacto en tiempo de compilación. Para formatos con estructura de directorio, usa un archivo `.zip`; para Javadoc, también funciona un `.jar` de un registro de paquetes como Maven Central. + +Los artefactos remotos tienen un límite de 50 MB comprimidos y 200 MB extraídos, siguen un tiempo de espera de 30 segundos y están protegidos contra redirecciones a direcciones privadas y contra zip-slip durante la extracción. + +
+ ## Páginas generadas +
+ +Cada conversor produce: + +- Navegación agrupada (por ejemplo, por módulo, paquete o namespace) que Mintlify añade a los `groups` de la pestaña. +- Una página MDX por cada clase, función, tipo o miembro documentado en el artefacto. +- Enlaces cruzados entre las páginas generadas, para que quienes leen puedan navegar entre tipos relacionados. + +Si el artefacto contiene elementos que no pertenecen a ningún grupo, Mintlify los agrupa bajo un grupo `Reference`. + +Puedes añadir tus propios `groups` escritos a mano a la misma pestaña. Se renderizan junto con los grupos generados. + +
+ ## Actualiza tu documentación +
+ +Mintlify regenera las páginas de referencia del SDK cuando ejecutas `mint dev` o cuando envías cambios a tu repositorio de documentación. Si el artefacto está alojado en una URL HTTPS, las actualizaciones del artefacto se regeneran en la siguiente compilación. diff --git a/fr.json b/fr.json index 6ab030d14..6fa1834b1 100644 --- a/fr.json +++ b/fr.json @@ -157,6 +157,7 @@ "fr/api-playground/mdx-setup", "fr/api-playground/asyncapi-setup", "fr/api-playground/graphql-setup", + "fr/api-playground/sdk-setup", "fr/api-playground/troubleshooting" ] }, diff --git a/fr/api-playground/sdk-setup.mdx b/fr/api-playground/sdk-setup.mdx new file mode 100644 index 000000000..639413b5e --- /dev/null +++ b/fr/api-playground/sdk-setup.mdx @@ -0,0 +1,128 @@ +--- +title: "Configuration de la référence SDK" +description: "Générez des pages de référence SDK à partir d’artefacts TypeDoc, DocFX, Javadoc, Sphinx ou phpDocumentor, afin que toute la documentation de vos SDK par langage vive dans votre site Mintlify." +keywords: ["sdk", "typedoc", "docfx", "javadoc", "sphinx", "phpdoc"] +--- + +Utilisez la propriété de navigation `sdk` pour publier des pages de référence SDK à partir d’artefacts produits par des générateurs de documentation courants. Mintlify lit l’artefact au moment de la build et développe l’onglet en un ensemble de pages MDX générées avec une navigation regroupée. + +
+ ## Formats pris en charge +
+ +| Format | Générateur | Artefact attendu | +| --------- | ----------------- | --------------------------------------------------- | +| `typedoc` | [TypeDoc](https://typedoc.org/) | Export JSON (`typedoc --json out.json`) | +| `docfx` | [DocFX](https://dotnet.github.io/docfx/) | Répertoire de sortie YAML `ManagedReference` | +| `javadoc` | [Javadoc](https://docs.oracle.com/javase/8/docs/technotes/tools/windows/javadoc.html) | Répertoire de sortie HTML du doclet standard (ou `.jar`) | +| `sphinx` | [Sphinx](https://www.sphinx-doc.org/) | Sortie du builder JSON (`sphinx-build -b json`) | +| `phpdoc` | [phpDocumentor](https://www.phpdoc.org/) | Fichier `structure.xml` | + +
+ ## Ajouter une référence SDK +
+ +Ajoutez une propriété `sdk` à un [onglet](/fr/organize/navigation#tabs) dans votre `docs.json`. Mintlify génère une page par classe, module, fonction ou type présent dans l’artefact, organisées en groupes. + + + +```json Local directory +"navigation": { + "tabs": [ + { + "tab": "SPA JS", + "sdk": { + "format": "typedoc", + "source": "sdk-artifacts/spa-js/typedoc.json" + } + } + ] +} +``` + +```json Remote URL +"navigation": { + "tabs": [ + { + "tab": "Java SDK", + "sdk": { + "format": "javadoc", + "source": "https://repo1.maven.org/maven2/com/example/sdk/1.0.0/sdk-1.0.0-javadoc.jar" + } + } + ] +} +``` + +```json Custom directory +"navigation": { + "tabs": [ + { + "tab": "SPA JS", + "sdk": { + "format": "typedoc", + "source": "sdk-artifacts/spa-js/typedoc.json", + "directory": "libraries/auth0-spa-js" + } + } + ] +} +``` + + + + + Vous devez déclarer `sdk` sur un onglet. Un onglet avec `sdk` peut inclure `groups`, mais aucune autre structure de navigation, telle que `pages`, `versions` ou `languages`. Il ne peut pas non plus inclure de propriété `openapi`, `asyncapi` ou `graphql`. + + + + Le générateur de documentation qui a produit l’artefact. L’une des valeurs suivantes : `typedoc`, `docfx`, `javadoc`, `sphinx` ou `phpdoc`. + + + + Un chemin local vers l’artefact dans votre dépôt de documentation ou une URL HTTPS vers un artefact hébergé. Les URL HTTP ne sont pas acceptées. + + Pour les formats à fichier unique (`typedoc`, `phpdoc`), pointez vers le fichier. Pour les formats sous forme de répertoire (`docfx`, `javadoc`, `sphinx`), pointez vers le répertoire en local, ou vers une archive `.zip` ou `.jar` lorsqu’elle est distante. + + + + Le répertoire dans lequel les pages générées sont stockées. Par défaut, `sdk-reference`. + + +
+ ## Exclure les artefacts de votre build +
+ +Ajoutez votre répertoire d’artefacts à [`.mintignore`](/fr/organize/mintignore) afin que la sortie brute du générateur soit traitée comme une entrée de build, et non publiée en tant que fichiers statiques : + +```text .mintignore +sdk-artifacts/ +``` + +
+ ## Sources distantes +
+ +Lorsque `source` est une URL HTTPS, Mintlify récupère l’artefact au moment de la build. Pour les formats sous forme de répertoire, utilisez une archive `.zip` ; pour Javadoc, un `.jar` provenant d’un registre de paquets comme Maven Central fonctionne également. + +Les artefacts distants sont limités à 50 Mo compressés et 200 Mo extraits, respectent un délai d’expiration de 30 secondes, et sont protégés contre les redirections vers des adresses privées ainsi que contre le zip-slip lors de l’extraction. + +
+ ## Pages générées +
+ +Chaque convertisseur produit : + +- Une navigation regroupée (par exemple, par module, package ou namespace) que Mintlify ajoute aux `groups` de l’onglet. +- Une page MDX par classe, fonction, type ou membre documenté dans l’artefact. +- Des liens croisés entre les pages générées, afin que les lecteurs puissent naviguer entre les types associés. + +Si l’artefact contient des éléments qui n’appartiennent à aucun groupe, Mintlify les regroupe sous un groupe `Reference`. + +Vous pouvez ajouter vos propres `groups` rédigés à la main au même onglet. Ils s’affichent aux côtés des groupes générés. + +
+ ## Mettre à jour votre documentation +
+ +Mintlify régénère les pages de référence SDK lorsque vous exécutez `mint dev` ou lorsque vous poussez des modifications vers votre dépôt de documentation. Si l’artefact est hébergé à une URL HTTPS, les mises à jour de l’artefact sont régénérées lors de la prochaine build. diff --git a/zh.json b/zh.json index 277681565..66b585d09 100644 --- a/zh.json +++ b/zh.json @@ -154,6 +154,7 @@ "zh/api-playground/mdx-setup", "zh/api-playground/asyncapi-setup", "zh/api-playground/graphql-setup", + "zh/api-playground/sdk-setup", "zh/api-playground/troubleshooting" ] }, diff --git a/zh/api-playground/sdk-setup.mdx b/zh/api-playground/sdk-setup.mdx new file mode 100644 index 000000000..c8a8ad4e2 --- /dev/null +++ b/zh/api-playground/sdk-setup.mdx @@ -0,0 +1,128 @@ +--- +title: "SDK 参考设置" +description: "从 TypeDoc、DocFX、Javadoc、Sphinx 或 phpDocumentor 产物生成 SDK 参考页面，让所有语言 SDK 文档都汇集在你的 Mintlify 站点内。" +keywords: ["sdk", "typedoc", "docfx", "javadoc", "sphinx", "phpdoc"] +--- + +使用 `sdk` 导航属性，可以从常见文档生成器产出的产物中发布 SDK 参考页面。Mintlify 会在构建时读取产物，并将该 tab 扩展为一组带有分组导航的、自动生成的 MDX 页面。 + +
+ ## 支持的格式 +
+ +| 格式 | 生成器 | 预期产物 | +| ---------- | ----------------- | -------------------------------------------------- | +| `typedoc` | [TypeDoc](https://typedoc.org/) | JSON 导出文件 (`typedoc --json out.json`) | +| `docfx` | [DocFX](https://dotnet.github.io/docfx/) | `ManagedReference` YAML 输出目录 | +| `javadoc` | [Javadoc](https://docs.oracle.com/javase/8/docs/technotes/tools/windows/javadoc.html) | 标准 doclet 生成的 HTML 输出目录 (或 `.jar`) | +| `sphinx` | [Sphinx](https://www.sphinx-doc.org/) | JSON builder 输出 (`sphinx-build -b json`) | +| `phpdoc` | [phpDocumentor](https://www.phpdoc.org/) | `structure.xml` 文件 | + +
+ ## 添加 SDK 参考 +
+ +在 `docs.json` 中的某个 [tab](/zh/organize/navigation#tabs) 上添加 `sdk` 属性。Mintlify 会为产物中的每个 class、module、function 或 type 生成一个页面，并组织到相应的分组中。 + + + +```json Local directory +"navigation": { + "tabs": [ + { + "tab": "SPA JS", + "sdk": { + "format": "typedoc", + "source": "sdk-artifacts/spa-js/typedoc.json" + } + } + ] +} +``` + +```json Remote URL +"navigation": { + "tabs": [ + { + "tab": "Java SDK", + "sdk": { + "format": "javadoc", + "source": "https://repo1.maven.org/maven2/com/example/sdk/1.0.0/sdk-1.0.0-javadoc.jar" + } + } + ] +} +``` + +```json Custom directory +"navigation": { + "tabs": [ + { + "tab": "SPA JS", + "sdk": { + "format": "typedoc", + "source": "sdk-artifacts/spa-js/typedoc.json", + "directory": "libraries/auth0-spa-js" + } + } + ] +} +``` + + + + + 你必须在某个 tab 上声明 `sdk`。带有 `sdk` 的 tab 可以包含 `groups`，但不能包含其他导航结构，例如 `pages`、`versions` 或 `languages`。它也不能同时包含 `openapi`、`asyncapi` 或 `graphql` 属性。 + + + + 产出该产物的文档生成器。可选值为 `typedoc`、`docfx`、`javadoc`、`sphinx` 或 `phpdoc` 之一。 + + + + 指向文档仓库中产物的本地路径，或指向已托管产物的 HTTPS URL。不接受 HTTP URL。 + + 对于单文件格式 (`typedoc`、`phpdoc`) ，请指向该文件。对于目录形式的格式 (`docfx`、`javadoc`、`sphinx`) ，本地请指向目录；远程时请指向 `.zip` 或 `.jar` 归档文件。 + + + + 生成页面所存放的目录。默认值为 `sdk-reference`。 + + +
+ ## 从构建中排除产物 +
+ +将你的产物目录添加到 [`.mintignore`](/zh/organize/mintignore) 中，这样生成器的原始输出会作为构建输入被使用，而不会被作为静态文件发布： + +```text .mintignore +sdk-artifacts/ +``` + +
+ ## 远程源 +
+ +当 `source` 是 HTTPS URL 时，Mintlify 会在构建时获取该产物。对于目录形式的格式，请使用 `.zip` 归档；对于 Javadoc，也可以使用来自 Maven Central 等包注册中心的 `.jar` 文件。 + +远程产物的压缩体积上限为 50 MB，解压后上限为 200 MB，请求超时为 30 秒，并且会防止重定向到私有地址，以及在解压过程中防止 zip-slip 攻击。 + +
+ ## 生成的页面 +
+ +每个转换器都会产出： + +- 分组导航 (例如按 module、package 或 namespace 分组) ，Mintlify 会将其追加到该 tab 的 `groups` 中。 +- 为产物中记录的每个 class、function、type 或成员生成一个 MDX 页面。 +- 生成页面之间的相互链接，方便读者在相关类型之间跳转。 + +如果产物中包含不属于任何分组的项目，Mintlify 会将它们归入 `Reference` 分组。 + +你也可以在同一个 tab 中添加自己手写的 `groups`。它们会与自动生成的分组并排渲染。 + +
+ ## 更新你的文档 +
+ +当你运行 `mint dev` 或将更改推送到文档仓库时，Mintlify 会重新生成 SDK 参考页面。如果产物托管在 HTTPS URL 上，产物的更新会在下一次构建时被采纳。