Réduction

Bonne journée, chers collègues ! Après un long parcours d’apprentissage, tout le monde veut montrer à l’employeur ses fruits, et ne les montrer que du meilleur côté professionnel, n’est-ce pas ? Je pense que oui. Ainsi, en plus d'un projet correctement conçu et mis en œuvre, nous devons être capables de le formaliser. L'employeur ne lira pas tout le code de votre projet pour comprendre de quoi il s'agit et ce qu'il contient ? Dans cet article, nous allons enfin résumer les deux précédents, à savoir : Intégration Continue et Couverture du Code , et nous ferons comprendre sur la « front sheet » du projet open-source ce que nous avons utilisé dans notre projet et ce que cela représente. Aujourd'hui, nous allons vous parler de Markdown, poser nos questions préférées : « Qu'est-ce que c'est ? et "Pourquoi est-ce?", Voyons où il est utilisé et comment l'utiliser. Il y aura même un exemple, nous l'implémenterons dans notre projet open source . Alors allons-y!

Qu'est-ce que la « démarque » ?

Puisque vous et moi sommes programmeurs, nous allons immédiatement aller sur Google et ouvrir le premier lien Wiki , qui dit : Markdown est un langage de balisage léger créé dans le but d'écrire le texte le plus lisible et le plus facile à modifier, mais adapté à conversion vers des langages pour publications avancées (HTML, Rich Text et autres). Ici, pour être honnête, je n’ai pas grand chose à ajouter, je pense que c’est une explication presque parfaite.

Pourquoi avons-nous besoin de ce « Markdown » ?

Pour être honnête, ce n'est en fait pas mal sans cela :D Mais rappelons-nous notre objectif : écrire un modèle de projet compétent qui a déjà l'intégration continue et dispose de statistiques de couverture de code sur la ressource Codecov. Pourquoi ai-je mentionné cela ? De plus, Markdown nous permettra de récupérer les données de ces ressources et de fournir les données elles-mêmes, ou des badges qui nous redirigeront là où nous avons besoin d'obtenir ces informations. Il est pratique de tout avoir sur une seule page de « titre », plutôt que d’être dispersé à différents endroits, n’est-ce pas ?

Où est-il utilisé ?

Quiconque a téléchargé au moins une fois l'un de ses projets sur GitHub sait que GitHub souhaite constamment vous inviter à créer un fichier README : quelle est l'extension de ce fichier ? C'est vrai, Bolt connaît Markdown ! Comme nous le savons déjà, ce fichier s'adapte très facilement à de nombreux formats et est converti au format HTML dont nous avons besoin. Mais prenons notre temps et ne nous précipitons pas pour l'ajouter immédiatement directement à GitHub.

Comment travailler avec ?

Tout d’abord, comme vous l’avez peut-être remarqué, nous pouvons l’ajouter directement à GitHub et cela fonctionnera ! Mais nous n’avons pas toujours besoin de l’ajouter à un seul projet, par exemple. Ou par exemple, nous voulons réfléchir davantage à la façon dont nous le créons. Et là, GitHub ne nous convient plus. Et en général, nous pouvons créer des fichiers Markdown non seulement dans le but de les transférer vers GitHub. Deuxièmement, nous pourrions le créer directement via IDEA, ce qui est exactement ce que nous allons faire, mais pas tout de suite, car pourquoi avons-nous besoin d'un environnement de développement puissant pour écrire un petit fichier ? Ici, je recommande de parcourir le catalogue des éditeurs de fichiers Markdown simples et moins faciles. Pour ma part, j'ai choisi Haroopad , c'est très simple, accessible, a une représentation instantanée de ce que vous écrivez (IDEA aussi) et a une indication de syntaxe. Voici à quoi ressemble la fenêtre de l'éditeur : Ici, j'ai ouvert un fichier README.md prêt à l'emploi d'un de mes projets. À gauche se trouve une aide-mémoire, à droite se trouve un affichage, au centre se trouve du texte. Tout est très primitif et simple. Vous pouvez également voir des badges, dont nous parlerons sous peu. Ceux qui choisissent une manière différente d'écrire ces fichiers ne vous inquiétez pas, tout ce qui sera différent, c'est l'interface graphique. Le texte, la syntaxe et l'affichage resteront inchangés. Exemple La tâche est très simple : écrire README.md pour qu'il contienne : des informations sur le projet (y compris les badges), des informations sur l'importation du projet, des informations sur la mise en œuvre du projet, des informations sur les contacts de l'auteur. Tout est très simple et primitif, comme je l'ai déjà dit. Nous allons passer aux choses sérieuses.

1. Écrivons un titre - le nom de notre projet.

   Le titre principal et le plus grand est créé à l'aide de l'opérateur de hachage " # ", puis le titre est écrit. Dans notre cas:

   # ForJavaRushPublication

2. Ensuite, nous écrirons un titre légèrement plus petit et nous écrirons « Informations sur le projet ». Le plus petit en-tête est précédé d'un plus " # :

   ## Information

   Et puis nous rédigerons des informations sur le projet.

3. Insérons des liens vers nos articles. Cela se fait très simplement, et si vous utilisez Haroopad, tapez simplement l'aide-mémoire et le modèle sera inséré lui-même. La syntaxe est : " [text](url) " ;

4. Insérons des badges. Regardons de plus près ici.

   Tout d’abord, disposons-les sous forme de table, pour la beauté. Il y aura 2 colonnes et 2 colonnes. La syntaxe ressemblera à ceci :

   Et le résultat sera comme ceci :

   Ensuite, nous insérerons des hyperliens vers nos badges, mais où pouvons-nous les obtenir ? J'ai montré dans l'article précédent où obtenir Codecov, mais je n'ai pas mentionné lequel obtenir. Puisque nous avons un fichier Markdown, nous avons également besoin d'un badge Markdown :

   Copiez-le simplement et collez-le dans une colonne de notre Markdown. Mais n’oubliez pas que Codecov est apparu dans la branche JaCoCo, mais pas dans master, il faudra donc le corriger manuellement. Le badge Travis CI est placé directement en face du nom du projet, où le journal de construction est :

   Nous sélectionnons le badge, puis la fenêtre des paramètres apparaît :

   Nous sélectionnons définitivement Markdown et la branche dont vous avez besoin. Je vais créer README.md pour deux branches, et elles seront légèrement différentes, car je n'ai pas encore implémenté Codecov dans la branche master.




5. Écrivons des informations sur la façon d'importer ou de cloner ce projet. Je n'expliquerai pas comment faire cela, mais vous pouvez le lire dans mon README.md. Nous écrirons sur les technologies que nous avons utilisées dans notre projet, en plaçant des liens vers elles. Il s’agit néanmoins d’un projet pédagogique. Eh bien, notons les informations de contact.




6. Notre Markdown est prêt. Il ne nous reste plus qu'à l'ajouter à notre projet et le tour est joué. Mais pas tout d’un coup ! Ouvrons notre IDÉE, et dans Plugins, nous vérifions que vous disposez du support Markdown :

   J'ai Ultimate IDEA, donc j'ai tout, votre plugin n'est peut-être pas installé par défaut, mais lorsque vous créez un fichier avec l'extension md, vous devriez être invité à le télécharger. Téléchargez et redémarrez votre IDEA.




7. Après avoir importé le Markdown que nous avons écrit, ouvrez-le via IDEA et modifiez-le si nécessaire. Voici à quoi cela ressemble via IDEA :

   Nous poussons. Ensuite on voit qu'à l' ouverture d'un projet, les informations le concernant sont immédiatement chargées, c'est notre README.md :

   Désormais, lorsque nous cliquons sur le badge, nous pouvons accéder directement à l'assemblage du projet et voir ce que nous avons là et comment.




8. Je ferai la même chose pour la branche JaCoCo afin de démontrer Codecov Badge, car nous n'avons pas encore README.md dedans. Résultat, nous disposons désormais de deux badges :

   Codecov affiche le pourcentage de couverture de code, et il peut également nous rediriger vers la page Codecov et afficher un rapport détaillé de couverture de code.

Liens utiles

• Ce que Wiki nous dit à propos de Markdown ;
• Répertoire des éditeurs Markdown ;
• Haroopad que je recommande ;
• À propos de Markdown sur le site JetBrains ;
• Markdown Navigator sur le même JetBrains ;
• Les badges et tout ce qui les concerne. Ici, vous pouvez choisir le style de n'importe quel badge et le personnaliser vous-même ;
• Comment mettre à niveau votre projet open source ? Cet article répondra également ;
• Article précédent

Résumons la série de mes articles

1. Nous avons vu ce qu'est le CI, à quoi il sert et comment l'utiliser dans le premier article sur l'Intégration Continue ;
2. Nous avons joué avec CC et compris ce que c'est et pourquoi il est nécessaire dans le deuxième article sur la couverture de code ;
3. Et dans cet article, nous avons examiné ce qu'est Markdown, pourquoi il est nécessaire et comment l'utiliser efficacement.

Merci à tous d'avoir lu ces trois longs articles, j'espère qu'ils vous ont été utiles. Il peut y avoir des erreurs et des omissions dans le texte. Merci à tous pour votre attention !