Documentation des scripts Python pour les non-programmeurs

Question

Nous cherchons actuellement des moyens d'aider les membres hors-programme du groupe sysadmin à se familiariser avec les scripts Python utilisés pour les tâches sysadmin quotidiennes.

Est-ce que quelqu'un a des outils de documentation suggérés ou des pratiques exemplaires que nous pourrions trouver utiles à cette fin?

Modifier pour répondre commentaire de S. Lott:

D'abord, mes excuses pour être trop bref sur ma question initiale. Mon objectif principal est de m'assurer que quelqu'un, même un non-programmeur, est capable de dépanner facilement mes scripts si je ne suis pas là ce jour-là ou si je quitte l'organisation. Ce que je cherche, ce sont des pratiques utilisées par d'autres personnes qui ont le rôle de «codeur de script» dans un groupe technique tel qu'une équipe sysadmin. Par exemple, avant de commencer le script d'une tâche, j'ai pris l'habitude d'écrire d'abord un article dans notre wiki partagé expliquant chaque étape en détail. Je base ensuite mes scripts Python sur l'article - en l'utilisant comme pseudo-code.

D'autres exemples du genre de choses que je suis à la recherche pour:

• L'utilisation d'outils tels que Sphinx pour fournir facilement disponibles doc

• des discussions de groupe pour aller au-dessus du code avant la mise en production Permettre aux membres du groupe d'aller d'abord sur le processus manuellement (nous allons généralement cette route mais peut-être devrions-nous en faire une pratique plus courante)

Ou, tout aussi précieux sinon plus, négatifs tels que:

• Constaté que lourd commentant est une perte de temps parce que le flux logique est toujours étrangère aux non-programmeurs

• Lean vers l'utilisation pexpect en raison de la verbosité perdu lors de l'utilisation des modules de haut niveau

Ce ne sont là des exemples de choses auxquelles je pensais. J'espère que cela clarifie la question! Comme toujours, merci SO'ers.

Answer 1

Il existe un livre sur ce sujet - "Python pour l'administration du système Unix et Linux".

• http://oreilly.com/catalog/9780596515829

Et un article sur les travaux de développement qui pourrait vous fournir la saveur que vous pouvez suivre.

• http://www.ibm.com/developerworks/aix/library/au-python/

Et presque personne, quelle que soit la façon dont il va l'appliquer, voudrait travailler sur les bases de la langue elle-même.Il y a un bon démarrage sur le web en dehors du tutoriel qui est distribué avec la distribution standard de python.

• http://diveintopython3.ep.io/

Answer 2

Je trouve que l'utilisation argparse comme base pour l'analyse invocation du script/routage tend à produire une première ligne de bonne documentation. Si utilisé comme prévu, vos administrateurs système peuvent exécuter some_script --help pour obtenir une description de l'objectif du script et un résumé de ses options.

Il peut être assez simple de lier les sources de documentation utilisées par le code de construction de l'analyseur aux docstrings réelles des fonctions et des classes de votre code et à celles du script lui-même. Cela dépend de la complexité du script, mais cela peut souvent être un moyen peu coûteux d'obtenir suffisamment de documentation.