Comment marquer et documenter

Documenter votre travail¶

Leonardo Da Vinci a utilisé des revues pour dessiner, développer et finalement transmettre ses idées. Alexander von Humboldt a documenté plusieurs de ses voyages dans des journaux de voyage et Marie Skłodowska Curie a écrit la théorie de la “radioactivité” à l’aide de stylos et de papiers. Aujourd’hui, les médias écrits sont devenus des océans numériques infinis avec des outils sophistiqués pour documenter le code et les idées. De plus, la façon dont nous recherchons et récupérons des informations est passée de la recherche d’entrées de lexique à l’utilisation de mots clés dans les moteurs de recherche. Donc, si vous avez fait une découverte ingénieuse, vous voulez vous assurer que vous documentez bien afin que les autres puissent comprendre et utiliser. Vous voulez également vous assurer que d’autres peuvent trouver votre coup de génie dans les médias numériques. Vous voulez également vous assurer que d’autres peuvent trouver votre coup de génie dans les médias numériques. L’une des méthodes les plus répandues pour documenter et diffuser des idées est l’utilisation de wikis (d’Hawaï : fast), qui peuvent facilement être écrits en langage balisage. GitHub fournit des explications complètes et faciles à lire pour documentation de projet avec Markdown comme élément de base. Cette page présente les bases du langage de balisage pour tirer parti des wikis. En outre, la puissante alternative à l’utilisation de reStructuredText dans les documents basés sur Sphinx est introduite.

Quoi documenter ?¶

Une bonne documentation de code commence par une description qualitative et concise des capacités, des produits et des exigences des logiciels (p. ex., un paquet Python). Il fournit également des flux de travail pour installer et utiliser le logiciel, au mieux avec des exemples. Enfin, une bonne section de dépannage permet aux utilisateurs de trouver des problèmes dans leur configuration de données ou l’utilisation de logiciels. Pour permettre le développement et la maintenance futurs, une section Contribution fournit * des lignes directrices sur les bonnes pratiques* pour le codage de nouvelles capacités logicielles.

Présentez votre logiciel ou projet¶

Cette section vise à faire connaître les avantages et les capacités du logiciel : Dites brièvement aux utilisateurs le but du logiciel, pourquoi il est unique et ce qu’il produit.

Exigences¶

Une section sur les exigences devrait indiquer aux utilisateurs ou aux intervenants :

• Quelles sont les exigences du système?

• Quelles sont les dépendances du logiciel ou du projet (p. ex., d’autres paquets Python tels que NombrePy)?

• Quelles données d’entrée sont nécessaires pour exécuter le logiciel?

Installation¶

Une section d’installation doit décrire étape par étape l’installation du logiciel (par exemple, comment télécharger et accéder à votre paquet Python) ou le déroulement d’un projet. Les captures d’écran peuvent être utiles. La section Requirements devrait déjà avoir clarifié ce dont les utilisateurs ont besoin pour l’installation.

Utilisation¶

Une section sur l’utilisation doit décrire comment le logiciel peut être utilisé, en commençant par des bases telles que l’importation du logiciel comme paquet Python. En outre, il devrait mentionner les traitements possibles des données d’entrée et de sortie (c.-à-d., pré-traitement et post-traitement, respectivement). Si disponible, ajoutez des fonctionnalités plus complexes consécutivement dans un ordre logique.

Pour vraiment rendre votre logiciel utile aux autres, ajoutez une étude de cas. La plupart des utilisateurs ne liront pas la documentation de code détaillée avant d’obtenir le logiciel à exécuter une fois et voir ce qu’il peut faire. Un cas d’utilisation aide également à vérifier la logique de votre code et donne aux utilisateurs la possibilité de relier des sections de documentation de code imparfaites à leur flux de travail. Cela peut parfois être nécessaire, même si votre code est certainement parfait et que la documentation est infaillible.

Dépannage¶

Bien sûr, votre code et votre workflow sont exempts d’erreurs et bien sûr, seul l’utilisateur fait des erreurs. Quoi qu’il en soit, montrez de la compassion et intégrez des énoncés spécifiques Traitement des exceptions avec try - except dans le code source, ce qui indique les sources d’erreurs possibles. Ces messages d’erreur (et peut-être même d’avertissement) devraient tous être listés dans une section Troubleshoot de la documentation du code. Toute source d’erreur (message) doit être documentée sur les aspects suivants :

• Cause : Raisons possibles pour lesquelles une erreur se produit.

• Réparation: Étapes pour résoudre une erreur.

Contribution¶

Ton logiciel est génial. Pour rendre le logiciel encore plus brillant, infaillible et puissant, c’est une bonne idée (en fait : un must absolu) d’obtenir plus d’auteurs dans l’équipe de développement. Cependant, tout autre auteur a probablement des préférences individuelles en ce qui concerne les normes de code. Assurez-vous donc d’établir des règles claires pour les autres contributeurs dès le début. Par exemple, définissez des conventions de code claires comme expliqué dans la section Style de code et conventions.

Marquage¶

Pour rédiger une documentation d’un code ou d’un projet dans un format prêt à publier sur le Web, il est nécessaire d’établir un type de plate-forme croisée. À cette fin, Markdown représente un bon choix (entre autres, comme reStructuredText). Markdown a été créé en 2004 et est un langage de balisage simple qui est intuitif et facile à apprendre. Les langues de balisage structurent le contenu des documents en texte clair concernant la façon dont un document est affiché aux utilisateurs finaux (Rich Text Format). D’autres langues de balisage populaires sont par exemple TeX et XML (Extensible Markup Language). Markdown est devenu un outil populaire pour l’écriture syntaxique de texte d’ordinateur distinguable qui est ensuite traduit en Rich Text Format saveur. Voici un exemple du fonctionnement de Markdown:

# Better than Word-like rich text editors
*OS*-independent functionality:
- Avoid formatting of the same kind of thing redundantly (and inconsistently)
- Backwards compatibility
- Formulae handling
- ... and many more ...

Éditeurs de marquage (IDE)¶

De nombreux éditeurs de texte fournissent Markdown add-ons et Markdown-seulement les éditeurs perdent de plus en plus leur signification. Les éditeurs qui prennent simultanément en charge Markdown et les langages de programmation comme Python ou R sont à la fine pointe et donc recommandés.

Les éditeurs de texte de base qui supportent Markdown sont listés here. Les fichiers populaires et multi-plateformes IDE pour l’édition Markdown (.md) sont JupyterLab ou PyCharm.

Aperçu de la commande Markdown et mise en œuvre de l’image¶

Le tableau et les sections suivants donnent un aperçu des commandes de base. Il ya beaucoup plus d’options là-bas, que vous pouvez trouver en utilisant votre moteur de recherche préféré avec les mots clés markdown guide.

Feature	Code	Example
Blockquote	`	A quote`
Bold text	**Bold**	Bold
Code block (inline)	inline `code`	inline `code`
Heading 1	# Heading 1	Heading 1
Heading 2	## Heading 2	Heading 2
Heading 3	### Heading 3	Heading 3
Horizontal rule	*** or ===	-------
Hyperlink	[Link](https://fruitsinfo.com)	Link
Hyperlink to section	[Link](https://fruitsinfo.com)#apples	Link to apple-section
Image	
Italic text	*italic*	italic
Numbered list item	1. numbered item	1. Numbered item
Reference (defined)	[Defined Reference][wiki]	[Defined Reference][wiki]
Reference (definition)	[wiki]: https://wikipedia.org	Place at file bottom
Strikethrough	~~Strikethrough~~	~~Strikethrough~~

Itemisation (listes non numérotées)¶

Une section de liste détaillée peut être produite en utilisant *, +, ou - symboles avec des onglets qui déterminent l’indentation de la liste:

* level 1 item
    - level 2 item
    - another level 2 item
        + level 3 item
* next level 1 item

Tableaux¶

Les colonnes de tableau sont séparées par un signe |. La première ligne détermine les en-têtes de lignes et la deuxième ligne l’alignement par l’utilisation de : (voir l’exemple ci-dessous).

| Fruit | Kingdom | Genus |
|-------|:-------:|------:|
|Banana | Plantae | Musa  |
|Jackfruit|Plantae|Artocarpus|

Converting complex tables from workbooks (e.g., from LibreOffice Calc or MS Excel) is possible with many online tools, and here is just one example from Dave Johnson: https://thisDaveJ.com.

Expressions mathématiques : équations¶

Les expressions et équations mathématiques peuvent être implémentées en utilisant des signes $, semblables à LaTeX.

Html - Marquage¶

html structures peuvent être utilisés sans faille dans Markdown, qui n’est rien d’autre que simplifié html. Par conséquent, toute structure html peut être utilisée dans le balisage et l’implémentation de l’équation ci-dessus représente déjà le premier exemple d’utilisation html dans un document Markdown. Les sections suivantes donnent un aperçu de certains symboles html plus ou moins fréquemment utilisés qui fonctionnent également avec Markdown.

Lettres grecques¶

Pour utiliser les lettres grecques dans le texte en ligne, utilisez la langue html, où &lettername; produit le symbole de la lettre souhaitée Greek (par exemple, tapez δ à sortie δ ou Δ pour produire une lettre majuscule Δ). Le tableau suivant donne un aperçu des symboles grecs.

Flèches et opérateurs¶

Les flèches et les opérateurs peuvent également être implémentés sous forme de symboles html. Le tableau suivant donne un aperçu.

Symboles divers¶

Markdown bénéficie de beaucoup plus de symboles html qui peuvent être utilisés dans des équations ou d’autres textes. Le tableau suivant donne un aperçu de ces symboles divers.

Wikis¶

Alors que chaque dépôt git devrait au moins contenir un descriptif README.md, wiki fournit beaucoup plus de détails et de conseils. Les Wikis sont une façon pratique de guider les utilisateurs avec des sidebars permanents (comme la barre de menus sur ce site), aider les utilisateurs à comprendre les méthodes et les codes, et le codage collaboratif avec des descriptions précises des scripts. Les utilisateurs de GitHub trouvent des options pour activer wikis dans l’onglet Settings d’un dépôt et les développeurs continuent d’améliorer les fonctions de wiki (en savoir plus sur les wikis de GitHub).

Des wiki plus sophistiqués sont disponibles sur le site Web des thèmes Jekyll (p. ex., le thème git-wiki). Pour utiliser les thèmes Jekyll, assurez-vous d’activer GitHub pages (dans le dépôt Settings onglet) pour le dépôt où vous voulez établir le wiki (ce dépôt wiki est généralement un autre dépôt pour décrire un dépôt de code). Ensuite, installez l’environnement de développement Ruby et Jekyll (voir instructions sur leur site pour accéder et construire des centaines de thèmes pour la documentation de code et de projet. Des thèmes fourrés et adaptés localement peuvent alors être poussés vers un dépôt wiki distant en utilisant git.

reStructuredText, Sphinx et readthedocs¶

Une alternative au balisage est reStructuredText qui permet d’intégrer Python docstrings (en savoir plus sur Style de code et conventions) dans n’importe quel script avec Sphinx.

Sans Python ou connaissance de programmation, il pourrait être difficile de commencer avec Sphinx. Assurez-vous donc de comprendre les bases de Python et de documenter tout code avec docstrings, au mieux en utilisant google style formating. Une fois que vous commencez à documenter votre premier paquet Python, Google-style docstrings permettra la génération rapide de documents de haute qualité. À l’heure actuelle, l’une des meilleures options pour la production partielle de documentation de code, pour tout langage de programmation, est readthedocs, qui s’appuie sur Sphinx et reStructuredText.

[wiki] : https://wikipedia.org