TOC

Documenter le code Python: un guide complet

Documenter le code Python: un guide complet

Bienvenue dans votre guide complet de documentation du code Python. Que vous documentiez un petit script ou un grand projet, que vous soyez un débutant ou un Pythonista chevronné, ce guide couvrira tout ce que vous devez savoir.

Nous avons divisé ce didacticiel en quatre sections principales:

  1. Why Documenting Your Code Is So Important: Une introduction à la documentation et son importance

  2. Commenting vs. Documenting Code: Un aperçu des principales différences entre commenter et documenter, ainsi que les moments appropriés et les façons d'utiliser les commentaires

  3. Documenting Your Python Code Base Using Docstrings: Une plongée en profondeur dans les docstrings pour les classes, les méthodes de classe, les fonctions, les modules, les packages et les scripts, ainsi que ce qui devrait être trouvé dans chacun d'eux

  4. Documenting Your Python Projects: Les éléments nécessaires et ce qu'ils doivent contenir pour vos projets Python

N'hésitez pas à lire ce didacticiel du début à la fin ou à passer à une section qui vous intéresse. Il a été conçu pour fonctionner dans les deux sens.

Pourquoi la documentation de votre code est si importante

Heureusement, si vous lisez ce didacticiel, vous savez déjà l’importance de documenter votre code. Mais sinon, permettez-moi de citer quelque chose que Guido m'a mentionné lors d'un récent PyCon:

«Le code est plus souvent lu qu'écrit.»

-Guido van Rossum

Lorsque vous écrivez du code, vous l'écrivez pour deux publics principaux: vos utilisateurs et vos développeurs (vous y compris). Les deux publics sont tout aussi importants. Si vous êtes comme moi, vous avez probablement ouvert de vieilles bases de code et vous êtes demandé: "A quoi pensais-je?" Si vous rencontrez des problèmes pour lire votre propre code, imaginez ce que vos utilisateurs ou d'autres développeurs vivent lorsqu'ils essaient d'utiliser ou de contribuer à votre code.

Inversement, je suis sûr que vous avez rencontré une situation où vous vouliez faire quelque chose en Python et avez trouvé ce qui ressemble à une excellente bibliothèque qui peut faire le travail. Cependant, lorsque vous commencez à utiliser la bibliothèque, vous recherchez des exemples, des articles ou même de la documentation officielle sur la façon de faire quelque chose de spécifique et vous ne trouvez pas immédiatement la solution.

Après la recherche, vous vous rendez compte que la documentation fait défaut ou pire encore, manque complètement. C'est un sentiment frustrant qui vous dissuade d'utiliser la bibliothèque, quelle que soit la qualité ou l'efficacité du code. Daniele Procida a résumé le mieux cette situation:

«Peu importe la qualité de votre logiciel, carif the documentation is not good enough, people will not use it.»

-Daniele Procida

Dans ce guide, vous apprendrez de fond en comble comment documenter correctement votre code Python du plus petit des scripts au plus grand des projets Python pour éviter que vos utilisateurs ne se sentent trop frustrés d'utiliser ou de contribuer à votre projet.

Commentaire vs Documenter le code

Avant de pouvoir expliquer comment documenter votre code Python, nous devons distinguer la documentation du commentaire.

En général, les commentaires décrivent votre code pour / pour les développeurs. Le public principal visé est les mainteneurs et les développeurs du code Python. En conjonction avec un code bien écrit, les commentaires aident le lecteur à mieux comprendre votre code, son objectif et sa conception:

«Le code vous dit comment; Les commentaires vous expliquent pourquoi. "

-Jeff Atwood (aka Coding Horror)

La documentation du code décrit son utilisation et ses fonctionnalités à vos utilisateurs. Bien que cela puisse être utile dans le processus de développement, le principal public visé est les utilisateurs. La section suivante décrit comment et quand commenter votre code.

Principes de base du commentaire de code

Les commentaires sont créés en Python en utilisant le signe dièse (#) et doivent être de brèves instructions ne dépassant pas quelques phrases. Voici un exemple simple: 

def hello_world():
    # A simple comment preceding a simple print statement
    print("Hello World")

SelonPEP 8, les commentaires doivent avoir une longueur maximale de 72 caractères. Cela est vrai même si votre projet modifie la longueur de ligne maximale pour qu'elle soit supérieure aux 80 caractères recommandés. Si un commentaire va être supérieur à la limite de caractères de commentaire, l'utilisation de plusieurs lignes pour le commentaire est appropriée: 

def hello_long_world():
    # A very long statement that just goes on and on and on and on and
    # never ends until after it's reached the 80 char limit
    print("Hellooooooooooooooooooooooooooooooooooooooooooooooooooooooo World")

Commenter votre code sertmultiple purposes, including:

  • Planning and Reviewing: Lorsque vous développez de nouvelles parties de votre code, il peut être approprié d'utiliser d'abord les commentaires pour planifier ou décrire cette section de code. N'oubliez pas de supprimer ces commentaires une fois que le codage réel a été mis en œuvre et examiné / testé: 

    # First step
# Second step
# Third step

  • Les commentairesCode Description: peuvent être utilisés pour expliquer l'intention de sections spécifiques du code: 

    # Attempt a connection based on previous settings. If unsuccessful,
# prompt user for new settings.

  • Algorithmic Description: Lorsque des algorithmes sont utilisés, en particulier des algorithmes complexes, il peut être utile d’expliquer le fonctionnement de l’algorithme ou son implémentation dans votre code. Il peut également être approprié de décrire pourquoi un algorithme spécifique a été sélectionné par rapport à un autre. 

    # Using quick sort for performance gains

  • Tagging: L'utilisation du balisage peut être utilisée pour étiqueter des sections spécifiques du code où se trouvent des problèmes connus ou des domaines d'amélioration. Quelques exemples sont:BUG,FIXME etTODO. 

    # TODO: Add condition for when val is None

Les commentaires sur votre code doivent être brefs et ciblés. Évitez d'utiliser de longs commentaires lorsque cela est possible. De plus, vous devez utiliser les quatre règles essentielles suivantes en tant quesuggested by Jeff Atwood:

  1. Gardez les commentaires aussi près que possible du code décrit. Les commentaires qui ne sont pas proches de leur code de description sont frustrants pour le lecteur et sont facilement manquants lorsque des mises à jour sont effectuées.

  2. N'utilisez pas de mise en forme complexe (comme des tableaux ou des figures ASCII). Un formatage complexe conduit à un contenu distrayant et peut être difficile à maintenir au fil du temps.

  3. N'incluez pas d'informations redondantes. Supposons que le lecteur du code possède une compréhension de base des principes de programmation et de la syntaxe du langage.

  4. Concevez votre code pour qu'il se commente. La façon la plus simple de comprendre le code est de le lire. Lorsque vous concevez votre code à l'aide de concepts clairs et faciles à comprendre, le lecteur sera en mesure de conceptualiser rapidement votre intention.

N'oubliez pas que les commentaires sont conçus pour le lecteur, y compris vous-même, afin de l'aider à comprendre l'objectif et la conception du logiciel.

Commenter le code via Type Hinting (Python 3.5+)

L'indication de type a été ajoutée à Python 3.5 et est un formulaire supplémentaire pour aider les lecteurs de votre code. En fait, cela prend la quatrième suggestion de Jeff d'en haut au niveau suivant. Il permet au développeur de concevoir et d'expliquer des parties de leur code sans commenter. Voici un exemple rapide: 

def hello_name(name: str) -> str:
    return(f"Hello {name}")

En examinant l'indication de type, vous pouvez immédiatement dire que la fonction s'attend à ce que l'entréename soit de typestr, ou chaîne. Vous pouvez également dire que la sortie attendue de la fonction sera également de typestr, ou chaîne. Bien que l'indication de type aide à réduire les commentaires, sachez que cela peut également entraîner un travail supplémentaire lorsque vous créez ou mettez à jour la documentation de votre projet.

Vous pouvez en savoir plus sur l'indication de type et la vérification de type à partir dethis video created by Dan Bader.

Documentation de votre base de code Python à l'aide de Docstrings

Maintenant que nous avons appris à commenter, examinons en profondeur la documentation d'une base de code Python. Dans cette section, vous découvrirez les docstrings et comment les utiliser pour la documentation. Cette section est divisée en plusieurs sous-sections:

  1. Docstrings Background: Un arrière-plan sur le fonctionnement des docstrings en interne dans Python

  2. Docstring Types: Les différents «types» de docstring (fonction, classe, méthode de classe, module, package et script)

  3. Docstring Formats: Les différents «formats» de docstring (Google, NumPy / SciPy, ReStructured Text et Epytext)

Fond de Docstrings

La documentation de votre code Python est entièrement centrée sur les docstrings. Ce sont des chaînes intégrées qui, lorsqu'elles sont correctement configurées, peuvent aider vos utilisateurs et vous-même avec la documentation de votre projet. En plus des docstrings, Python possède également la fonction intégréehelp() qui imprime les objets docstring sur la console. Voici un exemple rapide:

>>> 

>>> help(str)
Help on class str in module builtins:

class str(object)
 |  str(object='') -> str
 |  str(bytes_or_buffer[, encoding[, errors]]) -> str
 |
 |  Create a new string object from the given object. If encoding or
 |  errors are specified, then the object must expose a data buffer
 |  that will be decoded using the given encoding and error handler.
 |  Otherwise, returns the result of object.__str__() (if defined)
 |  or repr(object).
 |  encoding defaults to sys.getdefaultencoding().
 |  errors defaults to 'strict'.
 # Truncated for readability

Comment cette sortie est-elle générée? Puisque tout en Python est un objet, vous pouvez examiner le répertoire de l'objet en utilisant la commandedir(). Faisons-le et voyons quelle trouvaille:

>>> 

>>> dir(str)
['__add__', ..., '__doc__', ..., 'zfill'] # Truncated for readability

Dans cette sortie de répertoire, il y a une propriété intéressante,__doc__. Si vous examinez cette propriété, vous découvrirez ceci:

>>> 

>>> print(str.__doc__)
str(object='') -> str
str(bytes_or_buffer[, encoding[, errors]]) -> str

Create a new string object from the given object. If encoding or
errors are specified, then the object must expose a data buffer
that will be decoded using the given encoding and error handler.
Otherwise, returns the result of object.__str__() (if defined)
or repr(object).
encoding defaults to sys.getdefaultencoding().
errors defaults to 'strict'.

Voilà! Vous avez trouvé où les docstrings sont stockées dans l'objet. Cela signifie que vous pouvez manipuler directement cette propriété. Cependant, il existe des restrictions pour les fonctions intégrées:

>>> 

>>> str.__doc__ = "I'm a little string doc! Short and stout; here is my input and print me for my out"
Traceback (most recent call last):
  File "", line 1, in 
TypeError: can't set attributes of built-in/extension type 'str'

Tout autre objet personnalisé peut être manipulé: 

def say_hello(name):
    print(f"Hello {name}, is it me you're looking for?")

say_hello.__doc__ = "A simple function that says hello... Richie style"

>>> 

>>> help(say_hello)
Help on function say_hello in module __main__:

say_hello(name)
    A simple function that says hello... Richie style

Python a une fonctionnalité supplémentaire qui simplifie la création de docstring. Au lieu de manipuler directement la propriété__doc__, le placement stratégique de la chaîne littérale directement sous l'objet définira automatiquement la valeur__doc__. Voici ce qui se passe avec le même exemple que ci-dessus: 

def say_hello(name):
    """A simple function that says hello... Richie style"""
    print(f"Hello {name}, is it me you're looking for?")

>>> 

>>> help(say_hello)
Help on function say_hello in module __main__:

say_hello(name)
    A simple function that says hello... Richie style

Voilà! Vous comprenez maintenant l'arrière-plan des docstrings. Il est maintenant temps d'en apprendre davantage sur les différents types de docstrings et sur les informations qu'ils doivent contenir.

Types de docstring

Les conventions de docstring sont décrites dansPEP 257. Leur objectif est de fournir à vos utilisateurs un bref aperçu de l'objet. Ils doivent être suffisamment concis pour être faciles à entretenir, mais être suffisamment élaborés pour que les nouveaux utilisateurs comprennent leur objectif et la manière d'utiliser l'objet documenté.

Dans tous les cas, les docstrings doivent utiliser le format de chaîne triple-double quote ("""). Cela doit être fait que la docstring soit multi-lignes ou non. Au minimum, une docstring devrait être un résumé rapide de tout ce que vous décrivez et devrait être contenue dans une seule ligne: 

"""This is a quick summary line used as a description of the object."""

Les docstrings à lignes multiples sont utilisées pour approfondir l'objet au-delà du résumé. Toutes les docstrings à lignes multiples ont les parties suivantes:

  • Une ligne récapitulative d'une ligne

  • Une ligne vierge reprenant le résumé

  • Toute autre élaboration pour le docstring

  • Une autre ligne vierge 

"""This is the summary line

This is the further elaboration of the docstring. Within this section,
you can elaborate further on details as appropriate for the situation.
Notice that the summary and the elaboration is separated by a blank new
line.
"""

# Notice the blank line above. Code should continue on this line.

Toutes les docstrings doivent avoir la même longueur maximale de caractères que les commentaires (72 caractères). Les Docstrings peuvent être divisés en trois grandes catégories:

  • Class Docstrings: Classe et méthodes de classe

  • Package and Module Docstrings: Package, modules et fonctions

  • Script Docstrings: Script et fonctions

Docstrings de classe

Les Docstrings de classe sont créés pour la classe elle-même, ainsi que pour toutes les méthodes de classe. Les docstrings sont placées immédiatement après la classe ou la méthode de classe en retrait d'un niveau: 

class SimpleClass:
    """Class docstrings go here."""

    def say_hello(self, name: str):
        """Class method docstrings go here."""

        print(f'Hello {name}')

Les docstrings de classe doivent contenir les informations suivantes:

  • Un bref résumé de son objectif et de son comportement

  • Toutes les méthodes publiques, avec une brève description

  • Toutes les propriétés de classe (attributs)

  • Tout ce qui concerne l'interface pour les sous-classes, si la classe est destinée à être sous-classée

Les paramètres du constructeur de classe doivent être documentés dans la docstring de la méthode de classe__init__. Les méthodes individuelles doivent être documentées à l'aide de leurs docstrings individuels. Les docstrings de méthode de classe doivent contenir les éléments suivants:

  • Une brève description de la méthode et de son utilisation

  • Tous les arguments (obligatoires et facultatifs) transmis, y compris les arguments de mots clés

  • Étiquetez tous les arguments considérés comme facultatifs ou ayant une valeur par défaut

  • Tout effet secondaire qui se produit lors de l'exécution de la méthode

  • Toutes exceptions levées

  • Toute restriction sur le moment où la méthode peut être appelée

Prenons un exemple simple d'une classe de données qui représente un animal. Cette classe contiendra quelques propriétés de classe, des propriétés d'instance, un__init__ et une méthode d'instance unique: 

class Animal:
    """
    A class used to represent an Animal

    ...

    Attributes
    ----------
    says_str : str
        a formatted string to print out what the animal says
    name : str
        the name of the animal
    sound : str
        the sound that the animal makes
    num_legs : int
        the number of legs the animal has (default 4)

    Methods
    -------
    says(sound=None)
        Prints the animals name and what sound it makes
    """

    says_str = "A {name} says {sound}"

    def __init__(self, name, sound, num_legs=4):
        """
        Parameters
        ----------
        name : str
            The name of the animal
        sound : str
            The sound the animal makes
        num_legs : int, optional
            The number of legs the animal (default is 4)
        """

        self.name = name
        self.sound = sound
        self.num_legs = num_legs

    def says(self, sound=None):
        """Prints what the animals name is and what sound it makes.

        If the argument `sound` isn't passed in, the default Animal
        sound is used.

        Parameters
        ----------
        sound : str, optional
            The sound the animal makes (default is None)

        Raises
        ------
        NotImplementedError
            If no sound is set for the animal or passed in as a
            parameter.
        """

        if self.sound is None and sound is None:
            raise NotImplementedError("Silent Animals are not supported!")

        out_sound = self.sound if sound is None else sound
        print(self.says_str.format(name=self.name, sound=out_sound))
Docstrings de paquet et de module

Les docstrings du package doivent être placés en haut du fichier__init__.py du package. Cette docstring doit répertorier les modules et sous-packages exportés par le package.

Les docstrings de module sont similaires aux docstrings de classe. Au lieu de documenter les classes et les méthodes de classe, c'est maintenant le module et toutes les fonctions qui s'y trouvent. Les docstrings du module sont placées en haut du fichier avant même toute importation. Les docstrings de module doivent inclure les éléments suivants:

  • Une brève description du module et de son objectif

  • Une liste de toutes les classes, exceptions, fonctions et autres objets exportés par le module

La docstring pour une fonction de module doit inclure les mêmes éléments qu'une méthode de classe:

  • Une brève description de la fonction et de son utilisation

  • Tous les arguments (obligatoires et facultatifs) transmis, y compris les arguments de mots clés

  • Étiquetez tous les arguments considérés comme facultatifs

  • Tout effet secondaire qui se produit lors de l'exécution de la fonction

  • Toutes exceptions levées

  • Toute restriction sur le moment où la fonction peut être appelée

Docstrings de script

Les scripts sont considérés comme des exécutables à fichier unique exécutés à partir de la console. Les docstrings pour les scripts sont placés en haut du fichier et doivent être suffisamment documentés pour que les utilisateurs puissent comprendre suffisamment comment utiliser le script. Il devrait être utilisable pour son message «usage», lorsque l'utilisateur passe incorrectement un paramètre ou utilise l'option-h.

Si vous utilisezargparse, vous pouvez omettre la documentation spécifique au paramètre, en supposant qu’elle soit correctement documentée dans le paramètrehelp de la fonctionargparser.parser.add_argument. Il est recommandé d'utiliser le__doc__ pour le paramètredescription dans le constructeur deargparse.ArgumentParser. Consultez notre tutoriel surCommand-Line Parsing Libraries pour plus de détails sur l'utilisation deargparse et d'autres analyseurs de ligne de commande courants.

Enfin, toute importation personnalisée ou tierce doit être répertoriée dans les docstrings pour permettre aux utilisateurs de savoir quels packages peuvent être requis pour exécuter le script. Voici un exemple de script utilisé pour imprimer simplement les en-têtes de colonne d'une feuille de calcul: 

"""Spreadsheet Column Printer

This script allows the user to print to the console all columns in the
spreadsheet. It is assumed that the first row of the spreadsheet is the
location of the columns.

This tool accepts comma separated value files (.csv) as well as excel
(.xls, .xlsx) files.

This script requires that `pandas` be installed within the Python
environment you are running this script in.

This file can also be imported as a module and contains the following
functions:

    * get_spreadsheet_cols - returns the column headers of the file
    * main - the main function of the script
"""

import argparse

import pandas as pd


def get_spreadsheet_cols(file_loc, print_cols=False):
    """Gets and prints the spreadsheet's header columns

    Parameters
    ----------
    file_loc : str
        The file location of the spreadsheet
    print_cols : bool, optional
        A flag used to print the columns to the console (default is
        False)

    Returns
    -------
    list
        a list of strings used that are the header columns
    """

    file_data = pd.read_excel(file_loc)
    col_headers = list(file_data.columns.values)

    if print_cols:
        print("\n".join(col_headers))

    return col_headers


def main():
    parser = argparse.ArgumentParser(description=__doc__)
    parser.add_argument(
        'input_file',
        type=str,
        help="The spreadsheet file to pring the columns of"
    )
    args = parser.parse_args()
    get_spreadsheet_cols(args.input_file, print_cols=True)


if __name__ == "__main__":
    main()

Formats de Docstring

Vous avez peut-être remarqué que, tout au long des exemples donnés dans ce tutoriel, il y a eu un formatage spécifique avec des éléments communs:Arguments,Returns etAttributes. Il existe des formats de docstrings spécifiques qui peuvent être utilisés pour aider les analyseurs et les utilisateurs de docstring à avoir un format familier et connu. La mise en forme utilisée dans les exemples de ce didacticiel sont des docstrings de style NumPy / SciPy. Certains des formats les plus courants sont les suivants:

Type de formatage La description Soutenu par Sphynx Spécification formelle

Google docstrings

Forme de documentation recommandée par Google

Yes

No

Texte reStructuré

Norme de documentation officielle Python; Pas adapté aux débutants mais riche en fonctionnalités

Yes

Yes

NumPy/SciPy docstrings

Combinaison NumPy de reStructured et de Google Docstrings

Yes

Yes

Epytext

Une adaptation Python d'Epydoc; Idéal pour les développeurs Java

Pas officiellement

Yes

La sélection du format docstring dépend de vous, mais vous devez vous en tenir au même format tout au long de votre document / projet. Voici des exemples de chaque type pour vous donner une idée de l'apparence de chaque format de documentation.

Exemple de Google Docstrings 
"""Gets and prints the spreadsheet's header columns

Args:
    file_loc (str): The file location of the spreadsheet
    print_cols (bool): A flag used to print the columns to the console
        (default is False)

Returns:
    list: a list of strings representing the header columns
"""
Exemple de texte restructuré 
"""Gets and prints the spreadsheet's header columns

:param file_loc: The file location of the spreadsheet
:type file_loc: str
:param print_cols: A flag used to print the columns to the console
    (default is False)
:type print_cols: bool
:returns: a list of strings representing the header columns
:rtype: list
"""
NumPy/SciPy Docstrings Example
"""Gets and prints the spreadsheet's header columns

Parameters
----------
file_loc : str
    The file location of the spreadsheet
print_cols : bool, optional
    A flag used to print the columns to the console (default is False)

Returns
-------
list
    a list of strings representing the header columns
"""
Exemple d'épytexte 
"""Gets and prints the spreadsheet's header columns

@type file_loc: str
@param file_loc: The file location of the spreadsheet
@type print_cols: bool
@param print_cols: A flag used to print the columns to the console
    (default is False)
@rtype: list
@returns: a list of strings representing the header columns
"""

Documenter vos projets Python

Les projets Python se présentent sous toutes sortes de formes, tailles et objectifs. La façon dont vous documentez votre projet doit correspondre à votre situation spécifique. Gardez à l'esprit qui seront les utilisateurs de votre projet et adaptez-vous à leurs besoins. Selon le type de projet, certains aspects de la documentation sont recommandés. La présentation générale du projet et sa documentation doivent être les suivantes: 

project_root/
│
├── project/  # Project source code
├── docs/
├── README
├── HOW_TO_CONTRIBUTE
├── CODE_OF_CONDUCT
├── examples.py

Les projets peuvent généralement être subdivisés en trois types principaux: privé, partagé et public / open source.

Projets privés

Les projets privés sont des projets destinés à un usage personnel uniquement et ne sont généralement pas partagés avec d'autres utilisateurs ou développeurs. La documentation peut être assez légère sur ces types de projets. Il y a quelques pièces recommandées à ajouter au besoin:

  • Readme: Un bref résumé du projet et de son objectif. Inclure toutes les exigences particulières pour l'installation ou l'exploitation du projet.

  • examples.py: Un fichier de script Python qui donne des exemples simples d'utilisation du projet.

N'oubliez pas, même si les projets privés vous sont destinés personnellement, vous êtes également considéré comme un utilisateur. Pensez à tout ce qui peut vous dérouter sur la route et assurez-vous de les capturer dans les commentaires, les docstrings ou le readme.

Projets partagés

Les projets partagés sont des projets dans lesquels vous collaborez avec quelques autres personnes dans le développement et / ou l'utilisation du projet. Le «client» ou utilisateur du projet continue d'être vous-même et les quelques personnes qui l'utilisent également.

La documentation devrait être un peu plus rigoureuse qu'elle ne devrait l'être pour un projet privé, principalement pour aider à intégrer de nouveaux membres au projet ou pour alerter les contributeurs / utilisateurs des nouveaux changements apportés au projet. Certaines des parties recommandées à ajouter au projet sont les suivantes:

  • Readme: Un bref résumé du projet et de son objectif. Inclure toutes les exigences particulières pour l'installation ou l'exploitation du projet. De plus, ajoutez toutes les modifications majeures depuis la version précédente.

  • examples.py: Un fichier de script Python qui donne des exemples simples d'utilisation des projets.

  • How to Contribute: Cela devrait inclure comment les nouveaux contributeurs au projet peuvent commencer à contribuer.

Projets publics et open source

Les projets publics et Open Source sont des projets qui sont destinés à être partagés avec un grand groupe d'utilisateurs et peuvent impliquer de grandes équipes de développement. Ces projets devraient accorder une priorité aussi élevée à la documentation du projet que le développement réel du projet lui-même. Certaines des parties recommandées à ajouter au projet sont les suivantes:

  • Readme: Un bref résumé du projet et de son objectif. Inclure toutes les exigences particulières pour l'installation ou l'exploitation des projets. De plus, ajoutez toutes les modifications majeures depuis la version précédente. Enfin, ajoutez des liens vers de la documentation supplémentaire, des rapports de bogues et toute autre information importante pour le projet. Dan Bader a rassembléa great tutorial sur ce que tout devrait être inclus dans votre readme.

  • How to Contribute: Cela devrait inclure comment les nouveaux contributeurs au projet peuvent aider. Cela inclut le développement de nouvelles fonctionnalités, la correction de problèmes connus, l'ajout de documentation, l'ajout de nouveaux tests ou la génération de rapports.

  • Code of Conduct: Définit comment les autres contributeurs doivent se traiter lors du développement ou de l'utilisation de votre logiciel. Cela indique également ce qui se passera si ce code est cassé. Si vous utilisez Github, un code de conduitetemplate peut être généré avec le libellé recommandé. Pour les projets Open Source en particulier, pensez à ajouter ceci.

  • License: Un fichier en clair décrivant la licence utilisée par votre projet. Pour les projets Open Source en particulier, pensez à ajouter ceci.

  • docs: Un dossier contenant de la documentation supplémentaire. La section suivante décrit plus en détail ce qui doit être inclus et comment organiser le contenu de ce dossier.

Les quatre sections principales du dossierdocs

Daniele Procida a donné un merveilleuxPyCon 2017 talk et lesblog post suivants sur la documentation des projets Python. Il mentionne que tous les projets devraient avoir les quatre sections principales suivantes pour vous aider à concentrer votre travail:

  • Tutorials: leçons qui prennent le lecteur par la main à travers une série d'étapes pour terminer un projet (ou un exercice significatif). Orienté vers l'apprentissage des utilisateurs.

  • How-To Guides: Guides qui guident le lecteur à travers les étapes nécessaires pour résoudre un problème courant (recettes orientées problème).

  • References: explications qui clarifient et éclairent un sujet particulier. Orienté vers la compréhension.

  • Explanations: descriptions techniques de la machine et son fonctionnement (classes clés, fonctions, API, etc.). Pensez à l'article Encyclopedia.

Le tableau suivant montre comment toutes ces sections sont liées les unes aux autres ainsi que leur objectif général:

Le plus utile lorsque nous étudions Le plus utile lorsque nous codons

Étape pratique

Tutoriels

Guides pratiques

Connaissance théorique

Explication

Référence

En fin de compte, vous voulez vous assurer que vos utilisateurs ont accès aux réponses à toutes les questions qu'ils peuvent avoir. En organisant votre projet de cette manière, vous pourrez répondre facilement à ces questions et dans un format dans lequel ils pourront naviguer rapidement.

Outils et ressources de documentation

Documenter votre code, en particulier les grands projets, peut être intimidant. Heureusement, il existe des outils et des références pour vous aider à démarrer:

Tool La description

Sphinx

Une collection d'outils pour générer automatiquement de la documentation dans plusieurs formats

Epydoc

Un outil pour générer la documentation API pour les modules Python en fonction de leurs docstrings

Lire les documents

Création automatique, gestion des versions et hébergement de vos documents pour vous

Doxygen

Un outil pour générer une documentation prenant en charge Python ainsi que plusieurs autres langages

MkDocs

Un générateur de site statique pour aider à construire la documentation du projet en utilisant le langage Markdown

pycco

Un générateur de documentation «rapide et sale» qui affiche le code et la documentation côte à côte. Découvrezour tutorial on how to use it for more info.

Outre ces outils, il existe des didacticiels, des vidéos et des articles supplémentaires qui peuvent être utiles lorsque vous documentez votre projet:

  1. Carol Willing - Sphinx pratique - PyCon 2018

  2. Daniele Procida - Développement basé sur la documentation - Leçons du projet Django - PyCon 2016

  3. Eric Holscher - Documenter votre projet avec Sphinx et lire la documentation - PyCon 2016

  4. Titus Brown, Luiz Irber - Créer, construire, tester et documenter un projet Python: un HOWTO pratique - PyCon 2016

  5. Documentation officielle du texte restructuré

  6. Apprêt de texte reStructuré de Sphinx

Parfois, la meilleure façon d'apprendre est d'imiter les autres. Voici quelques excellents exemples de projets qui utilisent bien la documentation:

Où est-ce que je commence?

La documentation des projets a une progression simple:

  1. Pas de documentation

  2. Quelques documents

  3. Documentation complète

  4. Bonne documentation

  5. Grande documentation

Si vous ne savez pas où aller avec votre documentation, regardez où en est votre projet par rapport à la progression ci-dessus. Avez-vous une documentation? Sinon, commencez par là. Si vous avez de la documentation mais qu'il manque certains des fichiers de projet clés, commencez par les ajouter.

En fin de compte, ne vous découragez pas ou ne vous laissez pas submerger par la quantité de travail requise pour documenter le code. Une fois que vous avez commencé à documenter votre code, il devient plus facile de continuer. N'hésitez pas à commenter si vous avez des questions ou contactez l'équipe Real Python sur les réseaux sociaux, et nous vous aiderons.

Related