From afe000e81d77b3b24e1fa88d8758277f553bba47 Mon Sep 17 00:00:00 2001 From: Cursor Agent Date: Fri, 23 Oct 2026 18:22:58 +0000 Subject: [PATCH] docs: add Go to SDK reference formats and document mintlify-go-extractor Co-authored-by: brandon --- .../skills/mintlify/reference/navigation.md | 2 +- api-playground/sdk-reference-setup.mdx | 44 ++++++++++++++++-- es/api-playground/sdk-reference-setup.mdx | 46 +++++++++++++++++-- es/organize/navigation.mdx | 2 +- fr/api-playground/sdk-reference-setup.mdx | 46 +++++++++++++++++-- fr/organize/navigation.mdx | 2 +- organize/navigation.mdx | 2 +- zh/api-playground/sdk-reference-setup.mdx | 46 +++++++++++++++++-- zh/organize/navigation.mdx | 2 +- 9 files changed, 167 insertions(+), 25 deletions(-) diff --git a/agent-context/context/skills/mintlify/reference/navigation.md b/agent-context/context/skills/mintlify/reference/navigation.md index 9344c1934a..726f449006 100644 --- a/agent-context/context/skills/mintlify/reference/navigation.md +++ b/agent-context/context/skills/mintlify/reference/navigation.md @@ -340,7 +340,7 @@ When you add `openapi` to a navigation element without specifying pages, Mintlif ## SDK references -Generate SDK reference pages from documentation-tool build artifacts by adding an `sdk` property to a tab or group. Set `format` to `typedoc`, `docfx`, `javadoc`, `sphinx`, or `phpdoc`; set `source` to an artifact path or HTTPS URL; and optionally set `directory` to control the generated pages' URL prefix (defaults to `sdk-reference`). Groups and pages inherit the nearest ancestor's `sdk` settings; a nested group with its own `sdk` overrides that inheritance. +Generate SDK reference pages from documentation-tool build artifacts by adding an `sdk` property to a tab or group. Set `format` to `typedoc`, `docfx`, `javadoc`, `sphinx`, `phpdoc`, or `go` (generate Go artifacts with `go run github.com/mintlify/mintlify-go-extractor@latest -o go.json` from inside the module); set `source` to an artifact path or HTTPS URL; and optionally set `directory` to control the generated pages' URL prefix (defaults to `sdk-reference`). Groups and pages inherit the nearest ancestor's `sdk` settings; a nested group with its own `sdk` overrides that inheritance. ```json { diff --git a/api-playground/sdk-reference-setup.mdx b/api-playground/sdk-reference-setup.mdx index f6bc20e2e1..955a6e77ea 100644 --- a/api-playground/sdk-reference-setup.mdx +++ b/api-playground/sdk-reference-setup.mdx @@ -1,8 +1,8 @@ --- 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"] +description: "Publish SDK reference documentation in Mintlify from TypeDoc, DocFX, Javadoc, Sphinx, phpDocumentor, or Go artifacts using the sdk navigation property." +keywords: ["sdk", "typedoc", "docfx", "javadoc", "sphinx", "phpdocumentor", "go", "golang", "mintlify-go-extractor", "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. It creates a page for every class, interface, module, and function. It also includes navigation groups, cross-page links, and search indexing. @@ -16,6 +16,7 @@ Use the `sdk` navigation property to generate reference pages for your SDK libra | `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 | +| `go` | [mintlify-go-extractor](https://github.com/mintlify/mintlify-go-extractor) (Go) | JSON artifact file | ## Generate an artifact @@ -44,8 +45,33 @@ python -m sphinx -b json docs/source artifacts/json phpdoc -d src -t artifacts --template=xml ``` +```bash Go +go run github.com/mintlify/mintlify-go-extractor@latest -o go.json +``` + +### Go + +Go's own documentation tools produce text and HTML, not a machine-readable artifact, so Mintlify maintains [`mintlify-go-extractor`](https://github.com/mintlify/mintlify-go-extractor), an open source command that writes one. Run it from anywhere inside your Go module. It reads your module's source files with the Go standard library, so it doesn't download dependencies or need credentials, and it works for private modules. + +With Go 1.24 or later, pin the extractor in your module's `go.mod` so every run uses the same version: + +```bash +go get -tool github.com/mintlify/mintlify-go-extractor@latest +go tool mintlify-go-extractor -o go.json +``` + +Each [release](https://github.com/mintlify/mintlify-go-extractor/releases) includes prebuilt binaries for macOS, Linux, and Windows. + +By default, the extractor documents every package in the module except `internal` packages and commands, and it reads doc comments as Markdown, which is what generated SDKs (for example, from Stainless, Speakeasy, or Fern) write. Common options: + +- `-comments=godoc`: read doc comments with Go's [doc comment syntax](https://go.dev/doc/comment) instead of Markdown. +- `-exclude`: skip packages, as a comma-separated list of package patterns. +- `-goos`, `-goarch`, `-tags`: choose the platform and build tags used to select files. The default is `linux/amd64`. + +Pass package patterns, such as `./option/...`, to document part of the module. See the [extractor README](https://github.com/mintlify/mintlify-go-extractor#readme) for every option. + ## Auto-populate SDK pages Add an `sdk` property to a tab or group in your `docs.json`. Mintlify parses the artifact. It creates navigation groups and pages for the library. @@ -89,7 +115,7 @@ A group with `sdk` can also list `pages` that you write yourself. Your pages app - The documentation tool that produced the artifact: `typedoc`, `docfx`, `javadoc`, `sphinx`, or `phpdoc`. + The documentation tool that produced the artifact: `typedoc`, `docfx`, `javadoc`, `sphinx`, `phpdoc`, or `go`. @@ -114,6 +140,8 @@ For TypeDoc artifacts, Mintlify follows the layout you define with `@category` a For Javadoc artifacts, Mintlify groups pages by package. When a package mixes kinds, it nests them under Interfaces, Classes, Enums, Records, Exceptions, Errors, and Annotations in the order Javadoc uses on its package pages. +For Go artifacts, Mintlify groups pages by package. Each package starts with an overview page that shows the package's `README` and doc comment, followed by an index of its types and functions. Each type and package-level function gets its own page. A type's page includes its fields, constructors, and methods. + 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. ## Customize a page for a single symbol @@ -137,10 +165,12 @@ Create a `Client` to call the API. The string form follows the pattern `[source] kind name`. If you leave out `source`, the page inherits it from the tab or group `sdk` config. The string form always inherits `format`, so it only works on pages under a tab or group with `sdk`. Everywhere else, set `sdk` to an object with the fields below. For methods and properties, include the parent name, such as `method Client.getUser`. +For Go artifacts, target structs and other defined types as `type`, interfaces as `interface`, struct fields as `property`, and package overview pages as `package`. Refer to a package by its name, followed by its directory path for nested packages, such as `package openai` or `package openai.option`. Add the package to a symbol name, such as `type option.RequestOption`, when more than one package has a symbol with that name. + If you leave out `title` or `description`, Mintlify uses the title and description generated for the symbol. - The symbol kind: `class`, `interface`, `enum`, `function`, `type`, `variable`, `method`, or `property`. + The symbol kind: `package`, `class`, `interface`, `enum`, `function`, `type`, `variable`, `method`, or `property`. @@ -151,6 +181,10 @@ If you leave out `title` or `description`, Mintlify uses the title and descripti Required for `method` and `property` targets. The enclosing class, interface, or type. + + For Go artifacts, the package that contains the symbol, such as `openai.option`. Use it when more than one package has a symbol with the same name. + + Overrides the inherited `format`. Required when the page is not under a tab or group with `sdk`. Only available in the object form. @@ -163,7 +197,7 @@ If you leave out `title` or `description`, Mintlify uses the title and descripti 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: +Single-file formats (`typedoc`, `phpdoc`, `go`) accept a direct file URL. Directory formats (`docfx`, `javadoc`, `sphinx`) accept a zip archive. Javadoc jars published to Maven Central work without repackaging: ```json { diff --git a/es/api-playground/sdk-reference-setup.mdx b/es/api-playground/sdk-reference-setup.mdx index f5bb424bcb..98354aae4e 100644 --- a/es/api-playground/sdk-reference-setup.mdx +++ b/es/api-playground/sdk-reference-setup.mdx @@ -1,7 +1,7 @@ --- title: "Configuración de referencias de SDK" -description: "Genera páginas de referencia de SDK a partir de tus herramientas de documentación existentes: TypeDoc, DocFX, Javadoc, Sphinx o phpDocumentor." -keywords: ["sdk", "typedoc", "docfx", "javadoc", "sphinx", "phpdocumentor", "reference"] +description: "Genera páginas de referencia de SDK a partir de tus herramientas de documentación existentes: TypeDoc, DocFX, Javadoc, Sphinx, phpDocumentor o Go." +keywords: ["sdk", "typedoc", "docfx", "javadoc", "sphinx", "phpdocumentor", "go", "golang", "mintlify-go-extractor", "reference"] --- Usa la propiedad de navegación `sdk` para generar páginas de referencia para tus bibliotecas de SDK a partir de las herramientas de documentación que ya utilizas. Mintlify lee el artefacto de compilación de cada herramienta. Después, crea una página para cada clase, interfaz, módulo y función, con grupos de navegación, enlaces entre páginas e indexación de búsqueda incluidos. @@ -17,6 +17,7 @@ Usa la propiedad de navegación `sdk` para generar páginas de referencia para t | `javadoc` | [Javadoc](https://docs.oracle.com/en/java/javase/17/javadoc/javadoc.html) (Java) | Directorio HTML del doclet estándar | | `sphinx` | [Sphinx](https://www.sphinx-doc.org) (Python) | Directorio de salida del builder JSON | | `phpdoc` | [phpDocumentor](https://phpdoc.org) (PHP) | Archivo `structure.xml` | +| `go` | [mintlify-go-extractor](https://github.com/mintlify/mintlify-go-extractor) (Go) | Archivo de artefacto JSON |
## Generar un artefacto @@ -47,8 +48,35 @@ python -m sphinx -b json docs/source artifacts/json phpdoc -d src -t artifacts --template=xml ``` +```bash Go +go run github.com/mintlify/mintlify-go-extractor@latest -o go.json +``` + +
+ ### Go +
+ +Las herramientas de documentación propias de Go generan texto y HTML, no un artefacto legible por máquina, por lo que Mintlify mantiene [`mintlify-go-extractor`](https://github.com/mintlify/mintlify-go-extractor), un comando de código abierto que lo genera. Ejecútalo desde cualquier ubicación dentro de tu módulo de Go. Lee los archivos fuente de tu módulo con la biblioteca estándar de Go, por lo que no descarga dependencias ni necesita credenciales, y funciona con módulos privados. + +Con Go 1.24 o posterior, fija el extractor en el `go.mod` de tu módulo para que cada ejecución use la misma versión: + +```bash +go get -tool github.com/mintlify/mintlify-go-extractor@latest +go tool mintlify-go-extractor -o go.json +``` + +Cada [versión](https://github.com/mintlify/mintlify-go-extractor/releases) incluye binarios precompilados para macOS, Linux y Windows. + +De forma predeterminada, el extractor documenta todos los paquetes del módulo excepto los paquetes `internal` y los comandos, y lee los comentarios de documentación como Markdown, que es lo que escriben los SDK generados (por ejemplo, con Stainless, Speakeasy o Fern). Opciones habituales: + +- `-comments=godoc`: lee los comentarios de documentación con la [sintaxis de comentarios de documentación](https://go.dev/doc/comment) de Go en lugar de Markdown. +- `-exclude`: omite paquetes, como una lista de patrones de paquete separados por comas. +- `-goos`, `-goarch`, `-tags`: elige la plataforma y las etiquetas de compilación usadas para seleccionar archivos. El valor predeterminado es `linux/amd64`. + +Pasa patrones de paquete, como `./option/...`, para documentar solo una parte del módulo. Consulta el [README del extractor](https://github.com/mintlify/mintlify-go-extractor#readme) para ver todas las opciones. +
## Generar automáticamente páginas de SDK
@@ -94,7 +122,7 @@ Un grupo con `sdk` también puede incluir `pages` que escribas tú mismo. Tus p - La herramienta de documentación que produjo el artefacto: `typedoc`, `docfx`, `javadoc`, `sphinx` o `phpdoc`. + La herramienta de documentación que produjo el artefacto: `typedoc`, `docfx`, `javadoc`, `sphinx`, `phpdoc` o `go`. @@ -121,6 +149,8 @@ Para los artefactos de TypeDoc, Mintlify sigue la organización que defines con Para los artefactos de Javadoc, Mintlify agrupa las páginas por paquete. Cuando un paquete mezcla tipos, los anida en Interfaces, Classes, Enums, Records, Exceptions, Errors y Annotations, en el orden que Javadoc usa en sus páginas de paquete. +Para los artefactos de Go, Mintlify agrupa las páginas por paquete. Cada paquete comienza con una página de resumen que muestra el `README` y el comentario de documentación del paquete, seguida de un índice de sus tipos y funciones. Cada tipo y cada función a nivel de paquete tiene su propia página. La página de un tipo incluye sus campos, constructores y métodos. + Cada página generada documenta una clase, interfaz, función, tipo u otro símbolo del artefacto y enlaza con las páginas generadas relacionadas. Si un convertidor produce páginas que no pertenecen a ningún grupo, Mintlify las recopila en un grupo `Reference`.
@@ -146,10 +176,12 @@ Crea un `Client` para llamar a la API. La forma de cadena sigue el patrón `[source] kind name`. Si omites `source`, la página lo hereda de la configuración `sdk` de la pestaña o del grupo. La forma de cadena siempre hereda `format`, por lo que solo funciona en páginas bajo una pestaña o grupo con `sdk`. En cualquier otro caso, establece `sdk` como un objeto con los campos que se indican a continuación. Para métodos y propiedades, incluye el nombre del elemento superior, por ejemplo `method Client.getUser`. +Para artefactos de Go, apunta a los structs y otros tipos definidos con `type`, a las interfaces con `interface`, a los campos de struct con `property` y a las páginas de resumen de paquete con `package`. Haz referencia a un paquete por su nombre, seguido de la ruta de su directorio para los paquetes anidados, como `package openai` o `package openai.option`. Añade el paquete al nombre de un símbolo, como `type option.RequestOption`, cuando más de un paquete tenga un símbolo con ese nombre. + Si omites `title` o `description`, Mintlify usa el título y la descripción generados para el símbolo. - El tipo de símbolo: `class`, `interface`, `enum`, `function`, `type`, `variable`, `method` o `property`. + El tipo de símbolo: `package`, `class`, `interface`, `enum`, `function`, `type`, `variable`, `method` o `property`. @@ -160,6 +192,10 @@ Si omites `title` o `description`, Mintlify usa el título y la descripción gen Requerido para símbolos de tipo `method` y `property`. La clase, interfaz o tipo que lo contiene. + + Para artefactos de Go, el paquete que contiene el símbolo, como `openai.option`. Úsalo cuando más de un paquete tenga un símbolo con el mismo nombre. + + Sobrescribe el `format` heredado. Obligatorio cuando la página no está bajo una pestaña o grupo con `sdk`. Solo disponible en la forma de objeto. @@ -174,7 +210,7 @@ Si omites `title` o `description`, Mintlify usa el título y la descripción gen Establece `source` como una URL HTTPS para obtener el artefacto en tiempo de compilación en lugar de incluirlo en tu repositorio de documentación. -Los formatos de archivo único (`typedoc`, `phpdoc`) aceptan una URL directa al archivo. Los formatos de directorio (`docfx`, `javadoc`, `sphinx`) aceptan un archivo zip. Los jars de Javadoc publicados en Maven Central funcionan sin necesidad de reempaquetarlos: +Los formatos de archivo único (`typedoc`, `phpdoc`, `go`) aceptan una URL directa al archivo. Los formatos de directorio (`docfx`, `javadoc`, `sphinx`) aceptan un archivo zip. Los jars de Javadoc publicados en Maven Central funcionan sin necesidad de reempaquetarlos: ```json { diff --git a/es/organize/navigation.mdx b/es/organize/navigation.mdx index f1b2a82752..2fd92ee0f6 100644 --- a/es/organize/navigation.mdx +++ b/es/organize/navigation.mdx @@ -608,7 +608,7 @@ Para obtener más información sobre cómo hacer referencia a endpoints de OpenA ## Referencias de SDK
-Genera páginas de referencia de SDK a partir de los artefactos de compilación de tus herramientas de documentación. Agrega una propiedad `sdk` a una pestaña con el `format` del artefacto (`typedoc`, `docfx`, `javadoc`, `sphinx` o `phpdoc`), una ruta `source` o URL HTTPS, y un `directory` opcional para el prefijo de URL de las páginas generadas. +Genera páginas de referencia de SDK a partir de los artefactos de compilación de tus herramientas de documentación. Agrega una propiedad `sdk` a una pestaña con el `format` del artefacto (`typedoc`, `docfx`, `javadoc`, `sphinx`, `phpdoc` o `go`), una ruta `source` o URL HTTPS, y un `directory` opcional para el prefijo de URL de las páginas generadas. Mintlify analiza el artefacto y genera grupos de navegación y páginas para cada clase, interfaz, módulo y función de la biblioteca. diff --git a/fr/api-playground/sdk-reference-setup.mdx b/fr/api-playground/sdk-reference-setup.mdx index 3ef4e182a7..48ea8f7744 100644 --- a/fr/api-playground/sdk-reference-setup.mdx +++ b/fr/api-playground/sdk-reference-setup.mdx @@ -1,7 +1,7 @@ --- title: "Configuration des références SDK" -description: "Générez des pages de référence SDK à partir de votre outillage de documentation existant : TypeDoc, DocFX, Javadoc, Sphinx ou phpDocumentor." -keywords: ["sdk", "typedoc", "docfx", "javadoc", "sphinx", "phpdocumentor", "reference"] +description: "Générez des pages de référence SDK à partir de votre outillage de documentation existant : TypeDoc, DocFX, Javadoc, Sphinx, phpDocumentor ou Go." +keywords: ["sdk", "typedoc", "docfx", "javadoc", "sphinx", "phpdocumentor", "go", "golang", "mintlify-go-extractor", "reference"] --- Utilisez la propriété de navigation `sdk` pour générer des pages de référence pour vos bibliothèques SDK à partir des outils de documentation que vous exécutez déjà. Mintlify lit l’artefact de build de chaque outil et crée une page pour chaque classe, interface, module et fonction. Les groupes de navigation, les liens entre les pages et l’indexation pour la recherche sont également inclus. @@ -17,6 +17,7 @@ Utilisez la propriété de navigation `sdk` pour générer des pages de référe | `javadoc` | [Javadoc](https://docs.oracle.com/en/java/javase/17/javadoc/javadoc.html) (Java) | Répertoire HTML du doclet standard | | `sphinx` | [Sphinx](https://www.sphinx-doc.org) (Python) | Répertoire de sortie du builder JSON | | `phpdoc` | [phpDocumentor](https://phpdoc.org) (PHP) | Fichier `structure.xml` | +| `go` | [mintlify-go-extractor](https://github.com/mintlify/mintlify-go-extractor) (Go) | Fichier d’artefact JSON |
## Générer un artefact @@ -47,8 +48,35 @@ python -m sphinx -b json docs/source artifacts/json phpdoc -d src -t artifacts --template=xml ``` +```bash Go +go run github.com/mintlify/mintlify-go-extractor@latest -o go.json +``` + +
+ ### Go +
+ +Les outils de documentation de Go produisent du texte et du HTML, pas un artefact lisible par une machine. Mintlify maintient donc [`mintlify-go-extractor`](https://github.com/mintlify/mintlify-go-extractor), une commande open source qui en génère un. Exécutez-la depuis n’importe quel emplacement de votre module Go. Elle lit les fichiers source de votre module avec la bibliothèque standard de Go : elle ne télécharge aucune dépendance, n’a besoin d’aucun identifiant et fonctionne avec les modules privés. + +Avec Go 1.24 ou une version ultérieure, épinglez l’extracteur dans le `go.mod` de votre module pour que chaque exécution utilise la même version : + +```bash +go get -tool github.com/mintlify/mintlify-go-extractor@latest +go tool mintlify-go-extractor -o go.json +``` + +Chaque [version](https://github.com/mintlify/mintlify-go-extractor/releases) inclut des binaires précompilés pour macOS, Linux et Windows. + +Par défaut, l’extracteur documente tous les packages du module, à l’exception des packages `internal` et des commandes, et lit les commentaires de documentation comme du Markdown, ce qu’écrivent les SDK générés (par exemple avec Stainless, Speakeasy ou Fern). Options courantes : + +- `-comments=godoc` : lit les commentaires de documentation avec la [syntaxe des commentaires de documentation](https://go.dev/doc/comment) de Go plutôt qu’en Markdown. +- `-exclude` : ignore des packages, sous la forme d’une liste de motifs de package séparés par des virgules. +- `-goos`, `-goarch`, `-tags` : choisissent la plateforme et les tags de build utilisés pour sélectionner les fichiers. La valeur par défaut est `linux/amd64`. + +Passez des motifs de package, comme `./option/...`, pour ne documenter qu’une partie du module. Consultez le [README de l’extracteur](https://github.com/mintlify/mintlify-go-extractor#readme) pour la liste complète des options. +
## Remplir automatiquement les pages SDK
@@ -94,7 +122,7 @@ Un groupe avec `sdk` peut aussi lister des `pages` que vous rédigez vous-même. - L’outil de documentation qui a produit l’artefact : `typedoc`, `docfx`, `javadoc`, `sphinx` ou `phpdoc`. + L’outil de documentation qui a produit l’artefact : `typedoc`, `docfx`, `javadoc`, `sphinx`, `phpdoc` ou `go`. @@ -121,6 +149,8 @@ Pour les artefacts TypeDoc, Mintlify suit l’organisation que vous définissez Pour les artefacts Javadoc, Mintlify regroupe les pages par package. Lorsqu’un package mélange plusieurs genres, il les imbrique sous Interfaces, Classes, Enums, Records, Exceptions, Errors et Annotations, dans l’ordre utilisé par Javadoc sur ses pages de package. +Pour les artefacts Go, Mintlify regroupe les pages par package. Chaque package commence par une page de présentation qui affiche le `README` et le commentaire de documentation du package, suivie d’un index de ses types et fonctions. Chaque type et chaque fonction au niveau du package dispose de sa propre page. La page d’un type comprend ses champs, ses constructeurs et ses méthodes. + Chaque page générée documente une classe, une interface, une fonction, un type ou un autre symbole de l’artefact et renvoie vers les pages générées associées. Si un convertisseur produit des pages qui n’appartiennent à aucun groupe, Mintlify les regroupe sous un groupe `Reference`.
@@ -146,10 +176,12 @@ Créez un `Client` pour appeler l’API. La forme chaîne suit le modèle `[source] kind name`. Si vous omettez `source`, la page l’hérite de la configuration `sdk` de l’onglet ou du groupe. La forme chaîne hérite toujours de `format` et ne fonctionne donc que sur les pages situées sous un onglet ou un groupe avec `sdk`. Dans tous les autres cas, définissez `sdk` comme un objet avec les champs ci-dessous. Pour les méthodes et propriétés, incluez le nom du parent, par exemple `method Client.getUser`. +Pour les artefacts Go, ciblez les structs et les autres types définis avec `type`, les interfaces avec `interface`, les champs de struct avec `property` et les pages de présentation de package avec `package`. Désignez un package par son nom, suivi du chemin de son répertoire pour les packages imbriqués, par exemple `package openai` ou `package openai.option`. Ajoutez le package au nom d’un symbole, par exemple `type option.RequestOption`, lorsque plusieurs packages ont un symbole portant ce nom. + Si vous omettez `title` ou `description`, Mintlify utilise le titre et la description générés pour le symbole. - Le type de symbole : `class`, `interface`, `enum`, `function`, `type`, `variable`, `method` ou `property`. + Le type de symbole : `package`, `class`, `interface`, `enum`, `function`, `type`, `variable`, `method` ou `property`. @@ -160,6 +192,10 @@ Si vous omettez `title` ou `description`, Mintlify utilise le titre et la descri Requis pour les cibles `method` et `property`. La classe, l’interface ou le type englobant. + + Pour les artefacts Go, le package qui contient le symbole, par exemple `openai.option`. Utilisez-le lorsque plusieurs packages ont un symbole portant le même nom. + + Remplace le `format` hérité. Requis lorsque la page ne se trouve pas sous un onglet ou un groupe avec `sdk`. Disponible uniquement dans la forme objet. @@ -174,7 +210,7 @@ Si vous omettez `title` ou `description`, Mintlify utilise le titre et la descri Définissez `source` sur une URL HTTPS pour récupérer l’artefact au moment du build au lieu de le committer dans votre dépôt de documentation. -Les formats à fichier unique (`typedoc`, `phpdoc`) acceptent une URL de fichier directe. Les formats à répertoire (`docfx`, `javadoc`, `sphinx`) acceptent une archive zip. Les jars Javadoc publiés sur Maven Central fonctionnent sans reconditionnement : +Les formats à fichier unique (`typedoc`, `phpdoc`, `go`) acceptent une URL de fichier directe. Les formats à répertoire (`docfx`, `javadoc`, `sphinx`) acceptent une archive zip. Les jars Javadoc publiés sur Maven Central fonctionnent sans reconditionnement : ```json { diff --git a/fr/organize/navigation.mdx b/fr/organize/navigation.mdx index 5e3ca999c6..72dc93bdb4 100644 --- a/fr/organize/navigation.mdx +++ b/fr/organize/navigation.mdx @@ -608,7 +608,7 @@ Pour plus d'informations sur la manière de référencer des endpoints OpenAPI d ## Références SDK
-Générez des pages de référence SDK à partir des artefacts de build de vos outils de documentation. Ajoutez une propriété `sdk` à un onglet avec le `format` de l’artefact (`typedoc`, `docfx`, `javadoc`, `sphinx` ou `phpdoc`), un chemin `source` ou une URL HTTPS, et un `directory` optionnel pour le préfixe d’URL des pages générées. +Générez des pages de référence SDK à partir des artefacts de build de vos outils de documentation. Ajoutez une propriété `sdk` à un onglet avec le `format` de l’artefact (`typedoc`, `docfx`, `javadoc`, `sphinx`, `phpdoc` ou `go`), un chemin `source` ou une URL HTTPS, et un `directory` optionnel pour le préfixe d’URL des pages générées. Mintlify analyse l’artefact et génère des groupes de navigation et des pages pour chaque classe, interface, module et fonction de la bibliothèque. diff --git a/organize/navigation.mdx b/organize/navigation.mdx index 721c291e34..3fea452210 100644 --- a/organize/navigation.mdx +++ b/organize/navigation.mdx @@ -585,7 +585,7 @@ For more information about referencing OpenAPI endpoints in your docs, see the [ ## SDK references -Generate SDK reference pages from the build artifacts of your documentation tools. Add an `sdk` property to a tab with the artifact `format` (`typedoc`, `docfx`, `javadoc`, `sphinx`, or `phpdoc`) and a `source` path or HTTPS URL. You can also add an optional `directory` for the URL prefix of generated pages. +Generate SDK reference pages from the build artifacts of your documentation tools. Add an `sdk` property to a tab with the artifact `format` (`typedoc`, `docfx`, `javadoc`, `sphinx`, `phpdoc`, or `go`) and a `source` path or HTTPS URL. You can also add an optional `directory` for the URL prefix of generated pages. Mintlify parses the artifact and generates navigation groups and pages for every class, interface, module, and function in the library. diff --git a/zh/api-playground/sdk-reference-setup.mdx b/zh/api-playground/sdk-reference-setup.mdx index 6a5b9f1054..6fb65e6d1c 100644 --- a/zh/api-playground/sdk-reference-setup.mdx +++ b/zh/api-playground/sdk-reference-setup.mdx @@ -1,7 +1,7 @@ --- title: "SDK 参考设置" -description: "了解如何使用 TypeDoc、DocFX、Javadoc、Sphinx 或 phpDocumentor 的构建产物，在 Mintlify 中自动生成 SDK 参考页面、导航分组、跨页链接和搜索索引，并通过 CI 或远程源保持内容更新。本文还介绍格式配置、目录路径、远程压缩包和仓库组织方式。" -keywords: ["sdk", "typedoc", "docfx", "javadoc", "sphinx", "phpdocumentor", "reference"] +description: "了解如何使用 TypeDoc、DocFX、Javadoc、Sphinx、phpDocumentor 或 Go 的构建产物，在 Mintlify 中自动生成 SDK 参考页面、导航分组、跨页链接和搜索索引，并通过 CI 或远程源保持内容更新。本文还介绍格式配置、目录路径、远程压缩包和仓库组织方式。" +keywords: ["sdk", "typedoc", "docfx", "javadoc", "sphinx", "phpdocumentor", "go", "golang", "mintlify-go-extractor", "reference"] --- 使用 `sdk` 导航属性，可以基于你已经在使用的文档工具，为 SDK 库生成参考页面。Mintlify 会读取每个工具生成的构建产物，为每个 class、interface、module 和 function 创建一个页面，并自动生成导航分组、跨页链接与搜索索引。 @@ -17,6 +17,7 @@ keywords: ["sdk", "typedoc", "docfx", "javadoc", "sphinx", "phpdocumentor", "ref | `javadoc` | [Javadoc](https://docs.oracle.com/en/java/javase/17/javadoc/javadoc.html) (Java) | 标准 doclet HTML 目录 | | `sphinx` | [Sphinx](https://www.sphinx-doc.org) (Python) | JSON builder 输出目录 | | `phpdoc` | [phpDocumentor](https://phpdoc.org) (PHP) | `structure.xml` 文件 | +| `go` | [mintlify-go-extractor](https://github.com/mintlify/mintlify-go-extractor) (Go) | JSON 构建产物文件 |
## 生成构建产物 @@ -47,8 +48,35 @@ python -m sphinx -b json docs/source artifacts/json phpdoc -d src -t artifacts --template=xml ``` +```bash Go +go run github.com/mintlify/mintlify-go-extractor@latest -o go.json +``` + +
+ ### Go +
+ +Go 自带的文档工具只输出文本和 HTML，不会生成机器可读的构建产物，因此 Mintlify 维护了开源命令 [`mintlify-go-extractor`](https://github.com/mintlify/mintlify-go-extractor) 来生成构建产物。在你的 Go 模块内的任意位置运行它即可。它使用 Go 标准库读取模块的源文件，因此不会下载依赖，也不需要凭据，并且适用于私有模块。 + +使用 Go 1.24 或更高版本时，可以在模块的 `go.mod` 中固定该提取器，让每次运行都使用同一版本： + +```bash +go get -tool github.com/mintlify/mintlify-go-extractor@latest +go tool mintlify-go-extractor -o go.json +``` + +每个 [release](https://github.com/mintlify/mintlify-go-extractor/releases) 都附带适用于 macOS、Linux 和 Windows 的预编译二进制文件。 + +默认情况下，提取器会为模块中除 `internal` 包和命令之外的所有包生成文档，并将文档注释按 Markdown 读取，这也是生成式 SDK（例如由 Stainless、Speakeasy 或 Fern 生成的 SDK）所写的格式。常用选项： + +- `-comments=godoc`：按 Go 的[文档注释语法](https://go.dev/doc/comment)而不是 Markdown 读取文档注释。 +- `-exclude`：跳过指定的包，格式为以逗号分隔的包模式列表。 +- `-goos`、`-goarch`、`-tags`：选择用于筛选文件的平台和构建标签。默认值为 `linux/amd64`。 + +传入包模式（例如 `./option/...`）即可只为模块的一部分生成文档。完整选项请参阅[提取器 README](https://github.com/mintlify/mintlify-go-extractor#readme)。 +
## 自动填充 SDK 页面
@@ -94,7 +122,7 @@ phpdoc -d src -t artifacts --template=xml - 用于生成构建产物的文档工具：`typedoc`、`docfx`、`javadoc`、`sphinx` 或 `phpdoc`。 + 用于生成构建产物的文档工具：`typedoc`、`docfx`、`javadoc`、`sphinx`、`phpdoc` 或 `go`。 @@ -121,6 +149,8 @@ Mintlify 会将生成的导航组添加到 tab 中已有的任何 `groups` 之 对于 Javadoc 产物，Mintlify 会按包对页面进行分组。当一个包中混合了多种类型时，会按 Javadoc 包页面所用的顺序，将它们嵌套在 Interfaces、Classes、Enums、Records、Exceptions、Errors 和 Annotations 之下。 +对于 Go 产物，Mintlify 会按包对页面进行分组。每个包以一个概览页面开头，展示该包的 `README` 和文档注释，随后是其类型和函数的索引。每个类型和每个包级函数都有各自的页面。类型页面包含其字段、构造函数和方法。 + 每个生成的页面都记录了构建产物中的一个类、接口、函数、类型或其他符号，并链接到相关的生成页面。如果转换器生成的页面不属于任何组，Mintlify 会将它们归入 `Reference` 组。
@@ -146,10 +176,12 @@ sdk: "class Client" 字符串形式遵循 `[source] kind name` 的模式。如果省略 `source`，页面会从 tab 或 group 的 `sdk` 配置继承。字符串形式始终继承 `format`，因此只能用于带有 `sdk` 的 tab 或 group 下的页面。其他情况下，请将 `sdk` 设置为包含下述字段的对象。对于 method 和 property，请包含父级名称，例如 `method Client.getUser`。 +对于 Go 产物，struct 和其他自定义类型使用 `type`，interface 使用 `interface`，struct 字段使用 `property`，包概览页面使用 `package`。引用包时使用包名，嵌套包则在包名后加上其目录路径，例如 `package openai` 或 `package openai.option`。当多个包中有同名符号时，在符号名前加上包名，例如 `type option.RequestOption`。 + 如果省略 `title` 或 `description`，Mintlify 会使用为该符号生成的标题和描述。 - 符号类型：`class`、`interface`、`enum`、`function`、`type`、`variable`、`method` 或 `property`。 + 符号类型：`package`、`class`、`interface`、`enum`、`function`、`type`、`variable`、`method` 或 `property`。 @@ -160,6 +192,10 @@ sdk: "class Client" 对 `method` 和 `property` 目标为必填。所属的 class、interface 或 type。 + + 对于 Go 产物，表示包含该符号的包，例如 `openai.option`。当多个包中有同名符号时使用。 + + 覆盖继承的 `format`。当页面不属于带有 `sdk` 的 tab 或 group 时为必填。仅在对象形式中可用。 @@ -174,7 +210,7 @@ sdk: "class Client" 将 `source` 设置为 HTTPS URL，即可在构建时获取构建产物，而无需将其提交到文档仓库中。 -单文件格式（`typedoc`、`phpdoc`）可直接接受文件 URL。目录格式（`docfx`、`javadoc`、`sphinx`）接受 `zip` 压缩包。发布到 Maven Central 的 Javadoc jar 无需重新打包即可使用： +单文件格式（`typedoc`、`phpdoc`、`go`）可直接接受文件 URL。目录格式（`docfx`、`javadoc`、`sphinx`）接受 `zip` 压缩包。发布到 Maven Central 的 Javadoc jar 无需重新打包即可使用： ```json { diff --git a/zh/organize/navigation.mdx b/zh/organize/navigation.mdx index c709d44950..4098ec1891 100644 --- a/zh/organize/navigation.mdx +++ b/zh/organize/navigation.mdx @@ -575,7 +575,7 @@ boost: 3 ## SDK 参考
-基于文档工具的构建产物生成 SDK 参考页面。在某个 tab 上添加 `sdk` 属性，包括构建产物的 `format` (`typedoc`、`docfx`、`javadoc`、`sphinx` 或 `phpdoc`)、`source` 路径或 HTTPS URL，以及可选的 `directory`，用作生成页面的 URL 前缀。 +基于文档工具的构建产物生成 SDK 参考页面。在某个 tab 上添加 `sdk` 属性，包括构建产物的 `format` (`typedoc`、`docfx`、`javadoc`、`sphinx`、`phpdoc` 或 `go`)、`source` 路径或 HTTPS URL，以及可选的 `directory`，用作生成页面的 URL 前缀。 Mintlify 会解析构建产物，为库中的每个 class、interface、module 和 function 生成导航分组与页面。