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.
Formatos compatibles
Generar un artefacto
Generar automáticamente páginas de SDK
sdk a una pestaña o grupo en tu docs.json. Mintlify analiza el artefacto y crea grupos de navegación y páginas para la biblioteca.
sdk a un grupo para generar páginas dentro de una sección de una pestaña en lugar de en toda la pestaña. Los grupos y páginas heredan la configuración de sdk de la pestaña o grupo superior. Si un grupo anidado define su propio sdk, Mintlify usa esa configuración en lugar de la heredada.
sdk también puede incluir pages que escribas tú mismo. Tus páginas aparecen primero, seguidas de los grupos de referencia generados.
Puedes declarar
sdk en una pestaña o en un grupo.- Una pestaña con
sdkpuede incluirgroups, pero no otras estructuras de navegación, comopages,versionsolanguages. Tampoco puede incluir una propiedadopenapi,asyncapiographql. - Un grupo con
sdkpuede incluirpagesy grupos anidados, pero no puede incluir una propiedadgraphql.
string
requerido
La herramienta de documentación que produjo el artefacto:
typedoc, docfx, javadoc, sphinx o phpdoc.string
requerido
Ruta relativa al archivo o directorio del artefacto en tu repositorio de documentación, o una URL HTTPS. No admite URLs HTTP.
string
El prefijo de la ruta URL para las páginas generadas. El valor predeterminado es
sdk-reference.directory único para cada biblioteca para evitar colisiones de rutas.
Páginas generadas
groups en la pestaña. Si agregas sdk a un grupo, los grupos generados aparecen después de las pages de ese grupo. Los grupos varían según el formato y pueden representar módulos, paquetes, espacios de nombres o tipos de símbolos.
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.
Personalizar una página para un símbolo individual
sdk en una página MDX para apuntar a un símbolo del artefacto. Mintlify renderiza el contenido del cuerpo que escribas y, a continuación, añade debajo la referencia generada para ese símbolo. Utiliza esta opción cuando quieras agregar ejemplos, notas de migración o contexto sobre una clase, interfaz o método específicos.
Agrega la página a la navegación de tu docs.json como cualquier otra página. Mintlify solo genera contenido de SDK para las páginas que aparecen en tu navegación.
Cuando una pestaña o grupo con sdk contiene una página con frontmatter sdk, Mintlify deja de rellenar automáticamente esa pestaña o grupo y muestra solo las páginas que escribiste. Mueve la página fuera de la pestaña o grupo si quieres que el resto de la biblioteca se genere automáticamente.
Apunta sdk a un símbolo de una de estas dos maneras:
[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. Usa la forma de objeto en cualquier otro caso. Para métodos y propiedades, incluye el nombre del elemento superior, por ejemplo method Client.getUser.
Si omites title o description, Mintlify usa el título y la descripción generados para el símbolo.
string
requerido
El tipo de símbolo:
class, interface, enum, function, type, variable, method o property.string
requerido
El nombre del símbolo tal como aparece en el artefacto.
string
Requerido para símbolos de tipo
method y property. La clase, interfaz o tipo que lo contiene.string
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.string
Sobrescribe el
source heredado. Obligatorio cuando la página no está bajo una pestaña o grupo con sdk.Usar fuentes remotas
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:
Mantener las referencias actualizadas
source.
Configuración del repositorio
SDK y documentación en el mismo repositorio
source a su ruta relativa. Cualquier flujo de trabajo que ya produzca el artefacto al hacer push o durante una publicación puede confirmarlo en el repositorio. Después, publica las actualizaciones como parte del siguiente despliegue del sitio de documentación.
SDK en un repositorio separado
-
Confirma el artefacto en tu repositorio de documentación. En el repositorio del SDK, ejecuta un trabajo de CI al publicar una nueva versión. El trabajo debe generar el artefacto y abrir una solicitud de extracción (o hacer push de una confirmación) a tu repositorio de documentación con el archivo actualizado. Fusiona ese cambio en tu rama de despliegue para activar un despliegue del sitio. Apunta
sourcea la ruta confirmada, igual que en la configuración de un único repositorio. -
Aloja el artefacto y obténlo durante la compilación. Sube el artefacto a una URL HTTPS estable. Por ejemplo, un bucket de S3, un activo de GitHub Releases o Maven Central para jars de Javadoc. Establece
sourceen la URL. Activa un despliegue del sitio de documentación para obtener el nuevo artefacto cada vez que lo actualices. Llama al endpoint Activar despliegue desde el flujo de publicación de tu SDK después de publicar el artefacto.