Configurar el repositorio
Configurar el repositorio
Asumiendo que ya has completado la integración, el siguiente paso es configurar un repositorio.
Necesitas configurar correctamente tu repositorio para que Archbee pueda obtener el contenido y organizarlo adecuadamente en nuestro sistema.
Puedes hacer un fork de este repositorio.
Si el sistema encuentra un archivo .archbee.yaml en la raíz de tu repositorio u otras carpetas (en caso de que uses multipath) como este archivo .yaml, entonces lo usamos para organizar el contenido.
Presta mucha atención al archivo .yaml aquí si quieres configurar la carpeta desde la que se renderiza el contenido markdown (o una jerarquía de árbol de documentos de resumen).
Crear archivo .yaml
Crea un .archbee.yaml archivo con la siguiente estructura de variables:
Debes colocar el archivo en la carpeta raíz de tu(s) repositorio(s). Asegúrate de que el archivo permanezca allí, ya que esta es tu ruta predeterminada para otras carpetas. En caso de que tengas varias carpetas, debes copiar el archivo a esas carpetas. ¿Cómo, preguntas? Consulta cómo sincronizar múltiples carpetas.
¿Qué significan todas estas claves?
- root: ./docs : esta propiedad define dónde está el directorio que contiene la documentación (puede reemplazarse con docsPath: ./docs)
- structure:
- summary: summary.md : reconstruye el árbol del documento en el panel de navegación izquierdo en Archbee. Si no existe, consideramos que las carpetas son las categorías e imitamos la estructura de archivos interna.
- assets: assets : la carpeta de recursos es relativa a docsPath. Archbee subirá todos los archivos encontrados en esa carpeta (archivos de código e imágenes).
- shadowDocs : necesitas definir los archivos/carpetas de código que se incluirán como Shadow docs
- publishSpace : booleano, establécelo en true si deseas publicar el espacio en el portal de producción después de cada commit
Ejemplo de un archbee.yaml archivo de configuración:
root: doc-api
structure:
summary: summary.md
assets: assets
publishSpace: true
headerIncludes: |
<script>
document.getElementById("demo").innerHTML = "Hello JavaScript!";
</script> Ejemplo de un archbee.json archivo de configuración:
{
"root": "docfolderwithsummary",
"structure": {
"summary": "summary.md",
"assets": ".archbee/assets"
},
"customJS":"",
"customCSS":"* \n { font-family: \"Comic Sans MS\", cursive, sans-serif; }",
"footerTemplate": "",
"headerIncludes": ""
}Crear archivo summary.md
También recomendamos que crees un archivo summary.md. El summary.md reconstruye el árbol del documento en el panel de navegación izquierdo en Archbee. Y puede ayudarte a organizar tu contenido de manera adecuada.
Consulta un ejemplo de un archivo summary.md a continuación:
- [Introduction](1.md)
## Table of contents
- [Init](init.md)
- [Configure App](config.md)
- [Config Database](config-database.md)
- [Config Redis](config-redis.md)
- [Config Elastic Search](config-es.md)
- [Swagger](swagger-v2.json)
Usar sintaxis Markdown con GitHub
Algunos bloques de contenido pueden mostrarse si utilizas una sintaxis específica.
Consulta Atajos de Markdown del editor para usar estos atajos.
Añadir múltiples repositorios
Sigue estos sencillos pasos para añadir múltiples repositorios y sincronizarlos con Archbee:
Ve a tu cuenta de GitHub conectada con Archbee y luego navega a la página de Configuración.
En la barra lateral izquierda, busca Aplicaciones.
Haz clic en el botón Configurar y cuando se abra la nueva página, proporciona acceso a:
- Todos los repositorios (esto significa que puedes seleccionar cualquier repositorio desde tu cuenta de Archbee)
- Solo repositorios seleccionados (selecciona cualquier nuevo repositorio que quieras sincronizar con Archbee)
- Haz clic en Guardar
Regresa a tu cuenta de Archbee.
Desde el panel de navegación izquierdo, crea un nuevo Espacio -> elige Escribir en GitHub y selecciona los repositorios recién añadidos.
Importar archivos Open API
En realidad puedes importar archivos Open API a través de GitHub. Esta función funciona exactamente como la función Importación de OpenAPI / Swagger incluyendo su configuración. Hay 2 cosas importantes que configurar:
- rutas a archivos Open Api (.json, .yml, .yaml) que deben escribirse en summary.md archivo de configuración
- ajustes que deben escribirse en el archivo de configuración principal bajo docTreeOptions:
docsPath: ./myapp-docs
structure:
summary: toc.md
assets: assets
docTreeOptions:
openApiTryIt: false
showDownloadOpenApiFile: true
shouldCreateSchemaCategory: true
shouldCreateIntro: true
openApiLanguageExamples:
- value: python
label: py
- value: javascript
label: js
footerTemplate: ""
headerIncludes: ""