angular/aio/README.md

Proyecto de documentación Angular (https://docs.angular.lat)

Todo en esta carpeta es parte del proyecto de documentación. Esto incluye:

• El sitio web para mostrar la documentación
• La configuración de dgeni para convertir los archivos de origen a archivos renderizados que se pueden vizualizar en el sitio web.
• Las herramientas para establecer ejemplos para el desarrollo; y generar archivos en tiempo real y archivos zip desde los ejemplos.

Tareas de desarrollador

Nosotros usamos Yarn para gestionar las dependencias y crear tareas de compilación. Debes ejecutar todas estas tareas desde la carpeta angular/aio. Aquí están las tareas más importantes que podrías necesitar usar:

• yarn - instalar todas las dependencias.

• yarn setup - instalar todas las dependencias, boilerplate, stackblitz, zips y ejecuta dgeni en los documentos.

• yarn setup-local - igual que setup, pero crea los paquetes de Angular a partir del código y usa estas versiones construidas localmente (en lugar de las recuperadas desde npm) para aio y ejemplos de documentos boilerplate.

• yarn build - crear una compilación de producción de la aplicación (después de instalar dependencias, boilerplate, etc).

• yarn build-local - igual que build, pero usa setup-local en lugar de setup.

• yarn build-local-with-viewengine - igual que build-local, pero además también enciende el modo ViewEngine (pre-Ivy) en aio. (Nota: Encender el modo ViewEngine en ejemplos de documentos, ver yarn boilerplate:add:viewengine abajo.)

• yarn start - ejecutar un servidor web de desarrollo que observa los archivos; luego crea el doc-viewer y vuelve a cargar la página, según sea necesario.

• yarn serve-and-sync - ejecutar ambos, el docs-watch y start en la misma consola.

• yarn lint - comprobar que el código del doc-viewer sigue nuestras reglas de estilo.

• yarn test - observar todos los archivos de origen, para el doc-viewer, y ejecuta todas las pruebas unitarias cuando haya algún cambio.

• yarn test --watch=false -ejecutar todas las pruebas unitarias una sola vez.

• yarn e2e - ejecutar todas las pruebas de e2e para el doc-viewer.

• yarn docs - generar toda la documentación desde los archivos fuente.

• yarn docs-watch - observar el código Angular, los archivos de documentación y ejecutar un 'doc-gen' en corto circuito para los documentos que fueron cambiados.

• yarn docs-lint - comprobar que el código del documento generado sigue nuestras reglas de estilo.

• yarn docs-test - ejecutar las pruebas unitarias para el código de generación de doc.

• yarn boilerplate:add - generar todo el código boilerplate para los ejemplos, para que puedan ejecutarse localmente.

• yarn boilerplate:add:viewengine - igual que boilerplate:add pero también enciende el modo ViewEngine (pre-Ivy).

• yarn boilerplate:remove - eliminar todo el código boilerplate que fue añadido a travésyarn boilerplate:add.

• yarn create-example - crear un nuevo directorio de ejemplo que contenga los archivos fuente iniciales.

• yarn generate-stackblitz - generar los archivos stackblitz que están usados por la etiqueta live-example en documentos.

• yarn generate-zips - generar los archivos zip desde los ejemplos. Zip está disponible a través de la etiqueta live-example en los documentos.

• yarn example-e2e - ejecutar todas las pruebas e2e para ejemplos. Opciones disponibles:

  • --setup: generar boilerplate, forzar la actualización del controlador web y otras configuraciones, luego ejecutar las pruebas.
  • --local: ejecutar pruebas e2e con la versión local de Angular contenida en la carpeta "dist". Requiere --setup para que surta efecto.
  • --viewengine: ejecutar pruebas e2e en modo ViewEngine (pre-Ivy).
  • --filter=foo: limitar pruebas e2e a las que contienen la palabra "foo".

Nota para usuarios Windows

Configurar los ejemplos implica crear algunos enlaces simbólicos (ver Aquí para más detalles). En Windows, esto requiere tener Habilitado el Modo de desarrollador (compatible con Windows 10 o más reciente) o ejecutar los comandos de configuración cómo administrador.

Los comandos afectados son:

• yarn setup / yarn setup-*
• yarn build / yarn build-*
• yarn boilerplate:add
• yarn example-e2e --setup

Usando ServiceWorker localmente

Ejecutando yarn start (incluso cuando se apunta explícitamente al modo de producción) no configura el ServiceWorker. Si quieres probar el ServiceWorker localmente, puedes usar yarn build y luego ejecutar los archivos en dist/ con yarn http-server dist -p 4200.

Guía de autoría

Existen dos tipos de contenido en la documentación:

• Documentación de API: descripciones de los módulos, clases, interfaces, decoradores, etc que son parte de la plataforma Angular. La documentacion de API está generada directamente desde el código fuente. El código fuente está contenido en archivos TypeScript , almacenados en la carpeta angular/packages. Cada elemento de la API puede tener un comentario anterior, el cual contiene etiquetas y contenido de estilos JSDoc. El contenido está escrito en markdown.

• Otro contenido: guias, tutoriales, y otro material de marketing. Todos los demás contenidos se escriben utilizando markdown en archivos de texto, ubicados en la carpeta angular/aio/content. Más específicamente, hay subcarpetas que contienen tipos particulares de contenido: guías, tutoriales y marketing.

• Ejempos de código: los ejemplos de código deben ser comprobables para garantizar su precisión. Además, nuestros ejemplos tienen un aspecto específico y permiten al usuario copiar el código fuente. Para mayor ejemplos se representan en una interfaz con pestañas (e.g. template, HTML, y TypeScript en pestañas separadas). Adicionalmente, algunos son ejemplos en acción, que proporcionan enlaces donde se puede editar el código, ejecutar, y/o descargar. Para obtener más detalles sobre cómo trabajar con ejemplos de código, lea los fragmentos de código, código fuente de marcado , y ejemplos en acción paginas de los autores de guías de estilo .

Usamos la herramienta dgeni para convertir estos archivos en docs que se pueden ver en el doc-viewer. Las guías de estilo para Autores prescriben pautas para escribir páginas de guía, explica cómo usar la documentación de clases y componentes, y cómo marcar el código fuente para producir fragmentos de código.

Generando documentos completos

La principal tarea para generar los documentos es yarn docs. Esto procesará todos los archivos fuente (API y otros), extrayendo la documentación y generando archivos JSON que pueden ser consumidos por el doc-viewer.

Generación parcial de doc para editores

La generación completa de documentos puede llevar hasta un minuto. Eso es demasiado lento para la creación y edición eficiente de documentos.

Puedes ealizar pequeños cambios en un editor inteligente que muestre un markdown con formato:

En VS Code, Cmd-K, V abre la vista previa de markdown en el panel lateral; Cmd-B alterna la barra izquierda

Puedes también mirar los cambios que se muestran correctamente en el doc-viewer con un tiempo de ciclo rápido de edición / visualización.

Para este propósito, usa la tarea yarn docs-watch, que observa los cambios en los archivos de origen y solo vuelve a procesar los archivos necesarios para generar los documentos relacionados con el archivo que ha cambiado. Dado que esta tarea tiene accesos directos, es mucho más rápido (a menudo menos de 1 segundo) pero no producirá contenido de fidelidad completa. Por ejemplo, los enlaces a otros documentoss y ejemplos de código pueden no mostrarse correctamente. Esto se nota especialmente en los enlaces a otros documentos y en los ejemplos incrustados, que no siempre se representan correctamente.

La configuración general es la siguiente:

• Abrir una terminal, estar seguro que las dependencias están instaladas; ejecutar una generación inicial del doc; luego iniciar el doc-viewer:

yarn setup
yarn start

• Abrir una segunda terminal e iniciar el observador de documentos.

yarn docs-watch

Alternativamente, prueba el comando fusionado serve-and-sync que crea, observa y ejecuta en la misma ventana de la terminal

yarn serve-and-sync

• Abre un navegador con la siguiente dirección https://localhost:4200/ y navega hasta el documento en el que quieras trabajar. Puedes automáticamente abrir el navegador utilizando yarn start -o en la primera terminal.

• Realiza cambios en la página de documentación asociada o en los archivos de ejemplo. Cada vez que un archivo es guardado, la documentación se regenerará, la aplicación se reconstruirá y la página se volverá a cargar.

*Si recibes un error de compilación acerca de los ejemplos o cualquier otro error, asegúrate de consultar las guías de estilo para Autores para más información.