Construir una vista previa local

Fedora Documentation Team Last review: 2023-03-19
Una vista previa local es una herramienta valiosa para probar sus cambios cuando trabajo en su entorno de creación local. Ejecute el script docsbuilder disponible en el repositorio de contenido de Fedora. Puede crear y ejecutar el sitio completamente renderizado en su máquina para obtener una vista previa de los cambios que haya hecho antes de enviar una solicitud de extracción a los repositorios de contenido de Fedora.

Cuándo necesita una vista previa local

Cuando trabaja en su entorno de creación local, un vista previa local le proporciona y flujo de trabajo versátil para probar como sus cambios serán renderizados y trabajaran en su navegador localmente. Cuando realiza cambios tales como, entre otros;

  • Cambie enlaces o corrija enlaces rotos

  • Cambie el documento para documentar referencias cruzadas usando xref

  • Consolide múltiples página en un página

  • Actualice imágenes o corrija imágenes rotas

  • Añada metadatos o textos alternativos para las imágenes

  • Reorganice los niveles de sección (Ejemplo: h2 a h3, h3 a h4) para legibilidad y flujo de lectura

  • Corrija barra de navegación inactiva

  • Reorganice la barra de navegación

  • Vuelva a escribir páginas obsoletas

  • Añada atributos AsciiDoc

  • Reitere cambios y pruebas con un hilo vale

necesita crear scripts para representar los cambios de manera predecible y probarlos antes de hacer una solicitud de extracción.

Que hacen los scripts

Un script de creación de documentos unificado, docsbuilder.sh, crea una versión local del sitio, es decir el subconjunto del sitio completo que reside en su repositorio local. Sucesivamente, el script arranca un navegador web y sirve el sitio en http://localhost:8080/. Abrir este enlace en cualquier navegador web le mostrará la vista previa, que estará disponible hasta que mate el proceso (kbd:[Ctrl+C] en el terminal).

Consulte README.md en la página de inicio de los proyectos para ejecutar el script que se sugiere utilizar.

Como probar los cambios

Vaya al directorio donde clono el repositorio, cree, observe y obtenga una vista previa del sitios ejecutando los scripts de compilación en la terminal.

$ ./docsbuilder.sh

Pagure u otros repositorios de contenido muestran una script de compilación diferente.

$ ./builder.sh

Para usar los scripts necesita tener instalado Podman si usa Fedora Linux o Docker CE si usa macOS.

Vista previa de múltiples repositorios

Si su trabajo abarca contenido en múltiples repositorios, por ejemplo, por que usted enlazó a otro repositorio, puede extender la vista previa añadiendo más repositorios a site.yml como sigue:

content:
  sources:
  - url: .
    branches: HEAD
  - url: https://pagure.io/fedora-docs/another-repository.git
    branches: main

Las entradas correctas a usar se pueden encontrar en docs-fp-o site.yml.

Usar scripts regulares Antora

Si desea usar el flujo de trabajo normal de compilación y vista previa de Antora – siga las instrucciones de la página de Documentación Antora.

Una vez que tenga Antora CLI y Antora Site Generator puede compilar y obtener una vista previa de las páginas sin los scripts del contenedor.

Para compilar las páginas en el directorio del proyecto ejecute:

antora generate site.yml

Esto creará un nuevo directorio public que contiene todos los archivos necesarios. Navegue allí y ejecute un comando del servidor. Es posible que ya tenga un servidor simple Python, en cuyo caso ejecute:

python3 -m http.server

o sí solo tiene Python 2 en su máquina:

python -m SimpleHTTPServer

Abre una vista previa local en el puerto 8000.

Si tiene cargo (administrador de paquete Rust), podría también instalar y usar miniserve o cualquier otro servidor simple de su elección para este asunto.

Want to help? Learn how to contribute to Fedora Docs ›