Estructura del repositorio

Contenido

Esta es la principal referencia técnica de Bitxor. Contiene (o contendrá):

• Guías de usuario para las diferentes herramientas (Wallet, CLI, Explorer, etc.), destinadas a lectores no muy técnicos, que incluyen capturas de pantalla e instrucciones paso a paso sobre cómo resolver problemas comunes.

• Tutoriales para desarrolladores con ejemplos de código fuente en diferentes idiomas, organizados por temas. Desde introducción hasta guías detalladas sobre temas específicos.

• Definiciones de conceptos necesarias para entender el protocolo Bitxor.

• Guías de referencia técnica que describen cada punto final API y REST.

Debido a la complejidad del contenido técnico, se utiliza el motor Sphinx y reStructuredText en lugar del formato MarkDown más simple. Esto permite mucha más flexibilidad, por lo que podemos usar fragmentos de código en varios idiomas (con pestañas), macros de Python que recuperan contenido automáticamente de GitHub o tener más opciones de formato para tablas complejas, por ejemplo.

Edición

Este repositorio sigue el enfoque de documentos como código, lo que significa que trata la documentación como si fuera código fuente.

Para contribuir, debe consultar el repositorio de Git, realizar los cambios y enviar una Solicitud de extracción a GitHub. Los mantenedores del repositorio revisarán su contribución, sugerirán cambios si es necesario y eventualmente la fusionarán.

Probando localmente

Antes de enviar una solicitud de incorporación de cambios, es una buena idea probar los cambios localmente para asegurarse de que todo se muestre como se esperaba y que nada falle.

Primero necesita Instalar Sphinx. Básicamente, necesitas:

• Install Python 3.7

• Run pip install -r requirements.txt

Después de eso, puede activar una compilación ejecutándola desde la raíz del repositorio:

make livehtml

Esto genera todos los archivos HTML en la carpeta build/html, incluidos todos los activos como imágenes, javascript, CSS, fragmentos de código, etc. Esto también supervisa su carpeta de origen y regenera la salida cuando se detectan cambios. También instancia un servidor web en localhost:8000 para su conveniencia.

Despliegue

El repositorio de GitHub está vinculado a Travis, por lo que en cada inserción en la rama main se activa una compilación completa (ver ` .travis.yml` y la carpeta travis para más detalles). Esto implica varios pasos además de la generación de la documentación de salida:

• Validación de fragmentos de código fuente: las guías incluyen muchos ejemplos de código fuente que en realidad son fragmentos de programas completos. Estos programas deben compilarse y pasar verificaciones de pelusa en todo momento y Travis se asegura de ello. En este momento solo se verifican los programas TypeScript.

• Comprobación de enlaces: todas las páginas se examinan para encontrar enlaces rotos utilizando make linkcheck.

  La limitación está habilitada para evitar molestar demasiado a los servidores y obtener errores HTTP 429 Too Many Requests. Aún así, a veces su compilación falla debido a esto. Si detecta dicho error en los registros de Travis, inténtelo de nuevo.

  Si está seguro de que un enlace es correcto pero la verificación de enlaces en Travis sigue fallando, puede agregar este enlace en particular a la lista linkcheck_ignore en conf.py para omitir la verificación. Añade un comentario explicando el motivo.

• Localización: Las cadenas de texto se extraen de cada página usando make gettext y se suben a Transifex (ver la siguiente sección).

• Publicación: Las páginas HTML construidas se mueven a la carpeta docs en la rama gh-pages y se empujan. Las páginas de GitHub están configuradas para servirlas desde allí.

Debido a este proceso, los envíos a main normalmente tardan hasta 5 minutos en activarse.

Localización

En este momento, casi todas las páginas están disponibles en japonés además del inglés original, pero el repositorio está listo para aceptar más idiomas.

Transifex está integrado en el proceso de implementación, por lo que después de cada pulsación en main, Travis extrae y envía todas las cadenas (archivos .pot) a Transifex, que detecta cualquier texto nuevo o actualizado y notifica a los traductores.

Los traductores pueden iniciar sesión en Transifex y proporcionar las traducciones allí. Luego, los desarrolladores pueden descargar el texto actualizado (archivos .po) y enviarlos al repositorio fuente.

Hasta ahora, este proceso lo ha realizado en su totalidad la comunidad de Bitxor, incluso confirmando los textos actualizados y enviando solicitudes de extracción.

Edición

Este repositorio sigue el enfoque de documentos como código, lo que significa que trata la documentación como si fuera código fuente.

Para contribuir, debe consultar el repositorio de Git, realizar los cambios y enviar una Solicitud de extracción a GitHub. Los mantenedores del repositorio revisarán su contribución, sugerirán cambios si es necesario y eventualmente la fusionarán.

Probando localmente

Antes de enviar una solicitud de incorporación de cambios, es una buena idea probar los cambios localmente para asegurarse de que todo se muestre como se esperaba y que nada falle.

Siga las instrucciones de `GitHub <https://docs.github.com/en/pages/setting-up-a-github-pages-site-with-jekyll/testing-your-github-pages-site-locally-with-jekyll >`__ para instalar una instancia local de Jekyll y ejecutarla.

Despliegue

La implementación es sencilla, ya que se utiliza una configuración de páginas de GitHub estándar (repositorio de GitHub + sitio de Jekyll + páginas de GitHub). Simplemente empuje a la rama gh-pages y se publicará en segundos.