Documentation de code avec Sphinx

Magazine
Marque
GNU/Linux Magazine
HS n°
Numéro
65
Mois de parution
mars 2013
Spécialité(s)


Résumé
Documenter un code est une perte de temps en première intention. On a le sentiment de ne pas être productif, que le projet sur lequel on travaille n'avance pas. Pourtant, pour peu que l'on développe en équipe ou que le projet soit mis en attente ne serait-ce qu'une semaine, la documentation va permettre de se remettre au travail beaucoup plus rapidement. Qui n'a jamais redécouvert un de ses propres codes au bout de quelques semaines sans comprendre comment il avait pu coder quelque chose d'aussi horrible/merveilleux ?

Python dispose d'un système de documentation intégré appelé pydoc. C'est à ce mécanisme que vous avez accès lorsque vous utilisez la fonction help() en mode interactif, ou que vous utilisez la commande pydoc du shell. La documentation se fait très simplement à l'aide de chaînes de caractères entre guillemets appelées docstrings. La PEP 0257 définit le bon usage de ces chaînes :

01: def ma_fonction(a, b):
02:  """
03:  Description de ce que fait ma_fonction
04: 
05:  Paramètres:
06:  a -- Description du paramètre a
07:  b -- Description du paramètre b
08:  """
09:  ...

En tapant ensuite help(ma_fonction) dans un interpréteur interactif, on obtiendra :

Help on function ma_fonction in module __main__:

ma_fonction(a, b)

    Description de ce que fait ma_fonction

    

    Paramètres:

    a -- Description du paramètre a

    b -- Description du paramètre b

(END)

Cette technique permet donc de documenter très simplement et très rapidement le code. Par contre, il n'y a aucune...

Cet article est réservé aux abonnés. Il vous reste 95% à découvrir.
S'abonner à Connect
  • Accédez à tous les contenus de Connect en illimité
  • Découvrez des listes de lecture et des contenus Premium
  • Consultez les nouveaux articles en avant-première
Je m'abonne


Article rédigé par

Par le(s) même(s) auteur(s)

Contrôler un serveur avec des SMS

Magazine
Marque
GNU/Linux Magazine
HS n°
Numéro
118
Mois de parution
février 2022
Spécialité(s)
Résumé

Utiliser des SMS pour communiquer avec un serveur peut paraître assez loufoque à notre époque. Pourtant, cela peut être très utile quand l’utilisateur final n’est pas un informaticien et que l’on ne souhaite pas nécessairement développer une application spécifique.

Les derniers articles Premiums

Les derniers articles Premium

Le combo gagnant de la virtualisation : QEMU et KVM

Magazine
Marque
Contenu Premium
Spécialité(s)
Résumé

C’est un fait : la virtualisation est partout ! Que ce soit pour la flexibilité des systèmes ou bien leur sécurité, l’adoption de la virtualisation augmente dans toutes les organisations depuis des années. Dans cet article, nous allons nous focaliser sur deux technologies : QEMU et KVM. En combinant les deux, il est possible de créer des environnements de virtualisation très robustes.

Brève introduction pratique à ZFS

Magazine
Marque
Contenu Premium
Spécialité(s)
Résumé

Il est grand temps de passer à un système de fichiers plus robuste et performant : ZFS. Avec ses fonctionnalités avancées, il assure une intégrité des données inégalée et simplifie la gestion des volumes de stockage. Il permet aussi de faire des snapshots, des clones, et de la déduplication, il est donc la solution idéale pour les environnements de stockage critiques. Découvrons ensemble pourquoi ZFS est LE choix incontournable pour l'avenir du stockage de données.

Générez votre serveur JEE sur-mesure avec Wildfly Glow

Magazine
Marque
Contenu Premium
Spécialité(s)
Résumé

Et, si, en une ligne de commandes, on pouvait reconstruire son serveur JEE pour qu’il soit configuré, sur mesure, pour les besoins des applications qu’il embarque ? Et si on pouvait aller encore plus loin, en distribuant l’ensemble, assemblé sous la forme d’un jar exécutable ? Et si on pouvait même déployer le tout, automatiquement, sur OpenShift ? Grâce à Wildfly Glow [1], c’est possible ! Tout du moins, pour le serveur JEE open source Wildfly [2]. Démonstration dans cet article.

Les listes de lecture

9 article(s) - ajoutée le 01/07/2020
Vous désirez apprendre le langage Python, mais ne savez pas trop par où commencer ? Cette liste de lecture vous permettra de faire vos premiers pas en découvrant l'écosystème de Python et en écrivant de petits scripts.
11 article(s) - ajoutée le 01/07/2020
La base de tout programme effectuant une tâche un tant soit peu complexe est un algorithme, une méthode permettant de manipuler des données pour obtenir un résultat attendu. Dans cette liste, vous pourrez découvrir quelques spécimens d'algorithmes.
10 article(s) - ajoutée le 01/07/2020
À quoi bon se targuer de posséder des pétaoctets de données si l'on est incapable d'analyser ces dernières ? Cette liste vous aidera à "faire parler" vos données.
Voir les 64 listes de lecture

Abonnez-vous maintenant

et profitez de tous les contenus en illimité

Je découvre les offres

Déjà abonné ? Connectez-vous