Reducción

¡Buenos días compañeros! Después de un largo camino de aprendizaje, todo el mundo quiere mostrarle al empleador sus frutos, y mostrárselo sólo desde el lado mejor y profesional, ¿verdad? Creo que sí. Por tanto, además de un proyecto correctamente diseñado e implementado, necesitamos ser capaces de formalizarlo. ¿El empleador no leerá todo el código de su proyecto para comprender de qué se trata y qué incluye? En este artículo, finalmente resumiremos los dos anteriores, a saber: Integración continua y cobertura de código , y comprenderemos en la hoja "frontal" del proyecto de código abierto qué usamos en nuestro proyecto y qué representa. Hoy te hablaremos sobre Markdown, haz nuestras preguntas favoritas: “¿Qué es?” y "¿Por qué es esto?", averigüemos dónde se usa y cómo trabajar con él. Incluso habrá un ejemplo, lo implementaremos en nuestro proyecto de código abierto . ¡Entonces vamos!

¿Qué es la "rebaja"?

Como usted y yo somos programadores, inmediatamente iremos a Google y abriremos el primer enlace Wiki , que dice: Markdown es un lenguaje de marcado liviano creado con el objetivo de escribir el texto más legible y fácil de editar, pero adecuado para conversión a idiomas para publicaciones avanzadas (HTML, Rich Text y otros). Aquí, para ser honesto, no tengo mucho que agregar, creo que esta es una explicación casi perfecta.

¿Por qué necesitamos esta "rebaja"?

Para ser honesto, en realidad no está mal sin él :D Pero recordemos nuestro objetivo: escribir una plantilla de proyecto competente que ya tenga Integración Continua y estadísticas de Cobertura de Código en el recurso Codecov. ¿Por qué mencioné esto? Además, Markdown nos permitirá tomar datos de estos recursos y proporcionarlos en sí, o insignias que nos redirigirán a donde necesitemos obtener esta información. Es conveniente tener todo en una sola página de “título”, en lugar de estar disperso en diferentes lugares, ¿no es así?

¿Dónde se usa?

Cualquiera que haya subido alguno de sus proyectos a GitHub al menos una vez sabe que GitHub quiere invitarlo persistentemente a crear un archivo README: ¿ Cuál es la extensión de este archivo? Así es, ¡ Bolt conoce Markdown! Como ya sabemos, este archivo se ajusta muy fácilmente a muchos formatos y se convierte al HTML que necesitemos. Pero tomemos nuestro tiempo y no nos apresuremos a agregarlo inmediatamente a GitHub.

¿Cómo trabajar con él?

Primero, como habrás notado, podemos agregarlo directamente a GitHub y ¡funcionará! Pero no siempre necesitamos agregarlo a un solo proyecto, por ejemplo. O por ejemplo queremos pensar más en cómo lo creamos. Y aquí GitHub ya no nos conviene. Y, en general, podemos crear archivos Markdown no solo con el fin de enviarlos a GitHub. En segundo lugar, podríamos crearlo directamente a través de IDEA, que es exactamente lo que haremos, pero no de inmediato, porque ¿por qué necesitamos un entorno de desarrollo potente para escribir un archivo pequeño? Aquí recomiendo navegar por el catálogo de editores de archivos Markdown fáciles y no tan fáciles. Para mí, elegí Haroopad , es muy simple, accesible, tiene una representación instantánea de lo que estás escribiendo (IDEA también) y tiene una sugerencia de sintaxis. Así es como se ve la ventana del editor: Aquí abrí un archivo README.md ya preparado de uno de mis proyectos. A la izquierda hay una hoja de trucos, a la derecha hay una pantalla y en el centro hay texto. Todo es muy primitivo y simple. También puedes ver insignias, de las que hablaremos en breve. Aquellos que elijan una forma diferente de escribir estos archivos no se alarmen, lo único que será diferente será la interfaz gráfica. El texto, la sintaxis y la visualización permanecerán sin cambios. Ejemplo La tarea es muy simple: escriba README.md para que contenga: información sobre el proyecto (incluidas las insignias), información sobre la importación del proyecto, información sobre la implementación del proyecto, información sobre los contactos del autor. Todo es muy sencillo y primitivo, como ya dije. Vamos a ir al grano.

1. Escribamos un título: el nombre de nuestro proyecto.

   El encabezado principal y más grande se crea usando el operador hash " # " y luego se escribe el título. En nuestro caso:

   # ForJavaRushPublication

2. Luego escribiremos un título un poco más pequeño y escribiremos "Información del proyecto". El encabezado más pequeño está precedido por más " # ":

   ## Information

   Y luego escribiremos información sobre el proyecto.

3. Insertemos enlaces a nuestros artículos. Esto se hace de manera muy simple, y si usa Haroopad, simplemente escriba la hoja de trucos y la plantilla se insertará sola. La sintaxis es: " [texto](url) ";

4. Insertemos insignias. Echemos un vistazo más de cerca aquí.

   Primero, dispongámoslos en forma de mesa, por belleza. Habrá 2 columnas y 2 columnas. La sintaxis se verá así:

   Y el resultado será así:

   A continuación, insertaremos hipervínculos a nuestras insignias, pero ¿dónde podemos conseguirlos? En el artículo anterior mostré dónde conseguir Codecov, pero no mencioné cuál conseguir. Como tenemos un archivo Markdown, también necesitamos una insignia de Markdown:

   Simplemente cópielo y péguelo en una columna de nuestro Markdown. Pero no olvides que Codecov apareció en la rama JaCoCo, pero no en master, por lo que tendrás que corregirlo manualmente. La insignia Travis CI se coloca justo enfrente del nombre del proyecto, donde se encuentra el registro de compilación:

   Elegimos la insignia y luego aparece la ventana de configuración:

   Definitivamente seleccionamos Markdown y la sucursal que necesitas. Crearé README.md para dos ramas y serán ligeramente diferentes porque todavía no he implementado Codecov en la rama maestra.




5. Escribamos información sobre cómo importar o clonar este proyecto. No explicaré cómo hacer esto, pero puedes leerlo en mi README.md. Escribiremos sobre las tecnologías que utilizamos en nuestro proyecto, colocando enlaces a ellas. Aún así, este es un proyecto educativo. Bueno, anotemos la información de contacto.




6. Nuestro Markdown está listo. Todo lo que tenemos que hacer es agregarlo a nuestro proyecto y listo. ¡Pero no todos a la vez! Abramos nuestra IDEA, y en Plugins comprobamos que tienes Markdown Support:

   Tengo Ultimate IDEA, así que lo tengo todo, es posible que su complemento no esté instalado de forma predeterminada, pero cuando crea un archivo con la extensión md, se le debe solicitar que lo descargue. Descarga y reinicia tu IDEA.




7. Después de importar el Markdown que escribimos, ábrelo a través de IDEA y edítalo si es necesario. Así es como se ve a través de IDEA:

   Empujamos. Luego vemos que al abrir un proyecto, inmediatamente se carga información sobre el mismo, este es nuestro README.md:

   Ahora, cuando hacemos clic en la insignia, podemos ir directamente al ensamblaje del proyecto y ver qué tenemos allí y cómo.




8. Haré lo mismo para la sucursal de JaCoCo para demostrar la insignia Codecov, porque todavía no tenemos README.md. Como resultado, ahora tenemos dos insignias:

   Codecov muestra el porcentaje de cobertura de código y también puede redirigirnos a la página de Codecov y mostrar un informe detallado de cobertura de código.

Enlaces útiles

• Lo que Wiki nos dice sobre Markdown;
• Directorio de editores de Markdown ;
• Haroopad que recomiendo;
• Acerca de Markdown en el sitio web de JetBrains ;
• Markdown Navigator en el mismo JetBrains;
• Insignias y todo sobre ellas. Aquí puedes elegir el estilo de cualquier insignia y personalizarla tú mismo;
• ¿Cómo actualizar su proyecto de código abierto? Este artículo también responderá ;
• Artículo anterior

Resumamos la serie de mis artículos.

1. Analizamos qué es la CI, para qué sirve y cómo utilizarla en el primer artículo sobre Integración Continua ;
2. Jugamos con CC y entendimos qué es y por qué es necesario en el segundo artículo sobre Cobertura de código ;
3. Y en este artículo analizamos qué es Markdown, por qué es necesario y cómo utilizarlo de forma eficaz.

Gracias a todos por leer estos tres largos artículos, espero que hayan sido útiles. Puede haber errores y omisiones en el texto. ¡Gracias a todos por su atención!