Guide de style de la documentation #

Ce guide contient les meilleures pratiques pour le langage et le formatage de la documentation Matplotlib.

Voir également

Pour plus d'informations sur la contribution, consultez la section Rédaction de documentation .

Langue explicative #

Pour la rédaction explicative, les lignes directrices suivantes visent à utiliser un langage clair et concis.

Terminologie #

Il existe plusieurs termes clés dans Matplotlib qui sont des normes de fiabilité et de cohérence dans la documentation. Ils ne sont pas interchangeables.

Terme	La description	Corriger	Incorrect
`Figure`	Espace de travail Matplotlib pour la programmation.	Pour les objets Matplotlib : Figure, "La Figure est l'espace de travail du visuel. Se référant à la classe : `Figure`, "Les méthodes au sein de la `Figure` fournissent les visuels." Langage général : figure, "Michelle Kwan est une célèbre patineuse artistique."	"La figure est l'espace de travail des visuels." "Les méthodes de la figure fournissent les visuels." "Le `Figure` Four leglock est un mouvement de lutte."
`Axes`	Sous-parcelles dans la figure. Contient des éléments de tracé et est responsable du traçage et de la configuration de détails supplémentaires.	Pour les objets Matplotlib : Axes, "Un Axes est une sous-parcelle dans la Figure." Se référant à la classe : `Axes`, "Chacune `Axes`est spécifique à une Figure." Langage général : haches, "Les bûcherons et les bûcherons utilisent des haches pour couper du bois." OU "Il n'y a pas de noms standard pour les coordonnées dans les trois axes." (Pluriel d'axe)	"Les méthodes d'axes transforment les données." "Chacun `Axes`est spécifique à une figure." "Les musiciens sur scène appellent leurs guitares Axes." "Le point où les Axes se rencontrent est l'origine du système de coordonnées."
`Artist`	Grande variété d'objets Matplotlib qui affichent des visuels.	Pour les objets Matplotlib : Artist, "Les artistes affichent des visuels et sont les éléments visibles lors du rendu d'une figure." Se référant à la classe : `Artist`, "Chacun `Artist` a des méthodes et des fonctions respectives." Langage général : artiste, "L'artiste du musée est français."	"Configurez l'artiste de légende avec sa méthode respective." "Il y a un `Artist` pour ce visuel dans le graphique." "Certains artistes ne sont devenus célèbres que par accident."
`Axis`	Objet unidimensionnel lisible par l'homme de marques de référence contenant des graduations, des étiquettes de graduation, des épines et des bords.	Pour les objets Matplotlib : Axis, "L'axe du graphique à barres est un artiste distinct." (pluriel, objets Axis) Se référant à la classe : `Axis`, "Le `Axis` contient les objets XAxis et YAxis respectifs." Langage général : axe, "La rotation autour d'un axe fixe est un cas particulier de mouvement de rotation."	"Tracer le graphique sur l'axe." "Chaque axe est généralement nommé d'après la coordonnée qui est mesurée le long de celui-ci." "Dans certains contextes d'infographie, l'ordonnée `Axis`peut être orientée vers le bas."
Programmation explicite orientée objet (POO)	Approche explicite de la programmation en Matplotlib.	Explicite explicite POO	orienté objet Style OO
Implicite, `pyplot`	Approche implicite de la programmation en Matplotlib avec `pyplot`module.	Implicite implicite `pyplot`	MATLAB comme Pyplot interface pyplot

Grammaire #

Sujet #

Utilisez des phrases impératives à la deuxième personne pour les instructions dirigées spécifiant une action. Les pronoms à la deuxième personne sont destinés à des contextes spécifiques à un individu et à une référence possessive.

Corriger	Incorrect
Installez Matplotlib à partir du répertoire source à l'aide du `pip` programme d'installation Python. Selon votre système d'exploitation, vous aurez peut-être besoin d'une assistance supplémentaire.	Vous pouvez installer Matplotlib à partir du répertoire source. Vous pouvez trouver une assistance supplémentaire si vous rencontrez des problèmes avec votre installation.

Temps #

Utilisez le présent simple pour les explications. Dans la mesure du possible, évitez le futur et les autres verbes modaux ou auxiliaires.

Corriger	Incorrect
Les idées fondamentales derrière Matplotlib pour la visualisation impliquent de prendre des données et de les transformer à travers des fonctions et des méthodes.	Matplotlib prendra des données et les transformera à travers des fonctions et des méthodes. Ils peuvent générer de nombreux types de visuels. Ce seront les bases pour utiliser Matplotlib.

Voix #

Écrivez en phrases actives. La voix passive est idéale pour les situations ou les conditions liées aux invites d'avertissement.

Corriger	Incorrect
La fonction `plot`génère le graphique.	Le graphique est généré par la `plot`fonction.
Un message d'erreur est renvoyé par la fonction s'il n'y a pas d'arguments.	Vous verrez un message d'erreur de la fonction s'il n'y a pas d'arguments.

Structure de la phrase #

Écrivez avec des phrases courtes en utilisant régulièrement l'ordre Sujet-Verbe-Objet. Limitez les conjonctions de coordination dans les phrases. Évitez les références aux pronoms et les phrases conjonctives subordonnées.

Corriger	Incorrect
Le `pyplot`module de Matplotlib est une collection de fonctions. Ces fonctions créent, gèrent et manipulent la figure et la zone de traçage actuelles.	Le `pyplot`module de Matplotlib est une collection de fonctions qui créent, gèrent et manipulent la figure actuelle et la zone de traçage.
La `plot`fonction trace les données sur les axes respectifs. Les Axes correspondent à la Figure respective.	La `plot`fonction trace les données dans ses axes respectifs pour sa figure respective.
L'approche implicite est un raccourci pratique pour générer des tracés simples.	Les utilisateurs qui souhaitent disposer de raccourcis pratiques pour générer des tracés utilisent l'approche implicite.

Formatage #

Les directives suivantes spécifient comment incorporer le code et utiliser le formatage approprié pour la documentation Matplotlib.

Numéro de code

Matplotlib est une bibliothèque Python et suit les mêmes normes de documentation.

Commentaires #

Des exemples de code Python ont des commentaires avant ou sur la même ligne.

Corriger	Incorrect
# Data years = [2006, 2007, 2008]	years = [2006, 2007, 2008] # Data
years = [2006, 2007, 2008] # Data	years = [2006, 2007, 2008] # Data

Sorties #

Lors de la génération de visuels avec Matplotlib à l'aide .pyde fichiers dans des exemples, affichez le visuel avec matplotlib.pyplot.showpour afficher le visuel. Gardez la documentation à l'écart des lignes de sortie Python.

Corriger	Incorrect
plt.plot([1, 2, 3], [1, 2, 3]) plt.show()	plt.plot([1, 2, 3], [1, 2, 3])
fig, ax = plt.subplots() ax.plot([1, 2, 3], [1, 2, 3]) fig.show()	fig, ax = plt.subplots() ax.plot([1, 2, 3], [1, 2, 3])

reStructuredText #

Matplotlib utilise reStructuredText Markup pour la documentation. Sphinx aide à transformer ces documents dans des formats appropriés pour l'accessibilité et la visibilité.

Listes #

Les listes à puces sont destinées aux éléments qui ne nécessitent pas de séquencement. Les listes numérotées servent exclusivement à effectuer des actions dans un ordre déterminé.

Corriger	Incorrect
L'exemple utilise trois graphiques.	L'exemple utilise trois graphiques.
Bar Ligne Tarte	Bar Ligne Tarte
Ces quatre étapes aident à démarrer avec Matplotlib.	Les étapes suivantes sont importantes pour commencer à utiliser Matplotlib.
Importez la bibliothèque Matplotlib. Importez les modules nécessaires. Définissez et attribuez des données sur lesquelles travailler. Transformez les données avec des méthodes et des fonctions.	Importez la bibliothèque Matplotlib. Importez les modules nécessaires. Définissez et attribuez des données sur lesquelles travailler. Transformez les données avec des méthodes et des fonctions.

Tableaux #

Utilisez des tableaux ASCII avec les normes reStructuredText pour organiser le contenu. Les tables Markdown et la directive csv-table ne sont pas acceptées.

Corriger

Incorrect

Corriger	Incorrect
D'ACCORD	Pas d'accord

| Correct | Incorrect |
| ------- | --------- |
| OK      | Not OK    |

+----------+----------+
| Correct  | Incorrect|
+==========+==========+
| OK       | Not OK   |
+----------+----------+

.. csv-table::
   :header: "correct", "incorrect"
   :widths: 10, 10

   "OK   ", "Not OK"

===========  ===========
  Correct     Incorrect
===========  ===========
OK           Not OK
===========  ===========

Ressources supplémentaires #

Ce guide de style n'est pas une norme exhaustive. Pour une référence plus approfondie sur la manière de contribuer à la documentation, consultez les liens ci-dessous. Ces ressources contiennent les meilleures pratiques courantes pour la rédaction de documentation.