Bonsoir,
tout est dans le titre.
Inscrivez-vous gratuitement
pour pouvoir participer, suivre les réponses en temps réel, voter pour les messages, poser vos propres questions et recevoir la newsletter
Qu'attendez-vous d'un outil de documentation de projets Python ?
Bonsoir,
tout est dans le titre.
bonsoir,
vaste sujet
- plusieurs types de sorties: html, pdf au minimum.
- des sorties avec style personnalisable (css pour html par exemple, pour pdf et latex je ne connais pas trop ce qui peut exister.) pour s'adapter aux contraintes de 'look and feel'.
- le support de plusieurs formatages de docstrings (dont le plain text de base qui permet de générer une doc même pour une librairie qui a pas été prévue pour)
- le support des extensions (c, cython, c++, fortran par exemple) pour homogénéiser les documentations.
- la possibilité d'insérer des images et des liens externes.
- la création du diagramme statique des classes, pas seulement l'héritage.
- la capacité de représenter des formules mathématiques.
Une compatibilité avec la syntaxe Doxygen
Si tu ne vis pas ce que tu penses alors tu penses ce que tu vis.
Bof, bof... J'ai parcouru la doc. et je trouve cela un peu "lourdingue". Ceci étant écrit, je regarderais la doc. un peu plus sérieusement pour voir si j'ai tors ou non.Envoyé par Bayard
On peut faire de petites personnalisations en LaTeX mais cela reste très technique.
J'irais même jusqu'à pouvoir insérer des petits applets Java dans certaines situations.
Pas mal d'outils de doc. bute sur ceci. Un outil comme MathJax permet une gestion des formules dans LaTeX et dans le HTML.
Moi autodidacte, moi pas comprendre...
Plus compliqué car il faut avoir un outil d'analyse du code pour chaque langage. Existent-ils des outils Python à la sauce ast pour ces langages ?
Salut,
j'y vais de ma petite liste (des ajouts à la réponse de kango) :
- que la doc soit navigable (ça parait tellement évident qu'on ne le dit même plus) ;
- un graphe de dépendances (je traque inlassablement les dépendances cycliques et ça permet d'avoir une vision du bousin dans son entier) à tous les niveaux : modules, classes, méthodes de classe et fonctions (conseil gratuit : snakefood fait ça très bien pour les modules) ;
- la philosophie "Batteries included" ;
- un code propre et facilement forkable ;
- une doc claire et à jour, générée par l'outil lui-même mais pas seulement : c'est jamais sympa de n'avoir que l'API et pas de doc/tuto à côté
.
Sur cette liste, les 3 derniers points peuvent d'ailleurs s'appliquer à tout projet Python (et pas seulement Python, d'ailleurs).
Bonsoir.
Oui mais même là-dessus, il faudrait trouver la meilleure méthode. Par exemple, j'ai du mal avec ce que propose Doxygen. Je m'en sors mais je ne trouve pas cela ergonomique.
Moi autodidacte, moi toujours pas comprendre...
C'est ce qui manque à epydoc mais j'avoue que je n'ai pas creusé beaucoup.
Peux-tu préciser ? Pour ma part, je vais me faire un petit outil de docu. de mon projet. Il va utiliser un langage de balise maison qui se veut simple, ce même langage servant à rédiger des pages HTML et des documents PDF via LaTeX, avec un support d'outils mathématiques. Est-ce à ce genre de chose que tu pensais ?* une doc claire et à jour, générée par l'outil lui-même mais pas seulement : c'est jamais sympa de n'avoir que l'API et pas de doc/tuto à côté
Entends-tu par là une dépendance pour les modules, et une autre pour les classes et les méthodes ? "J'm'en va" de ce pas regarder cette nourriture de serpent...
J'ai pas appris ça à l'école, mais en lisant des docs sur Python.
Alors, le concept de "Batteries included", c'est le fait que Python arrive avec une std lib assez fournie pour y trouver tout ce qu'il faut pour se faciliter la vie.
Les exemples qui me viennent à l'esprit parce que je les utilise souvent sont:
- la fonction os.walk ;
- le module shutil ;
- le module tempfile ;
- le module itertools (mon coup de coeur).
Appliqué à un outil de documentation, on peut imaginer :
- un serveur web local qui fait tourner la doc au format html (ce qui existe déjà avec pydoc) ;
- des scripts de formatage (xxx2html, xxx2pdf) ;
- l'intégration de ce générateur de doc avec le fichier setup.py ;
- tous les petits trucs qui sont faits à la pogne avec les autres outils alors qu'ils pourraient être automatisés (ok, c'est un peu vague, mais je sèche ^^... en même temps, j'ai parlé de "philosophie"
).
Pas du tout.
Ce que je veux dire, c'est un package, aussi bien foutu soit-il, perd beaucoup de son intérêt si la seule documentation est celle extraite du code.
Je conçois la documentation d'un module comme étant composée des choses suivantes :
- la doc de l'API (ta préoccupation) ;
- un fichier README ;
- un fichier CHANGES ;
- des tutoriels ;
- une FAQ ;
- une doc + "littéraire", qui expose des cas d'utilisations, des discussions qui n'ont pas leur place dans les docstrings (pour voir de quoi je veux parler, merci de consulter le documentation de n'importe quel module de la std lib sur le site officiel Python).
Peut-être sera-ce + clair si je te dis que les docstrings ne devraient pas contenir TOUTE la documentation de l'outil.
Concrètement, ça n'a rien à voir avec les buts de l'outil, mais j'estime qu'un outil digne de ce nom se doit d'avir une documentation fournie (et des tests, pendant qu'on y est).
Comme je le disais au paravent (), ce point là est générique et ne s'applique pas seulement à ton projet, ni même à un projet purement Python.
En fait, mais ça reste encore à l'état d'idée en gestation dans mon esprit, mais je vois un graphe de dépendance des modules et, quand tu cliques sur un module, je vois les dépendances des éléments de ce module (et pas uniquement internes à ce module : si une fonction de ce module appelle la fonction d'un autre module, cela devrait apparaître).
Cela dit, c'est peut-être un peu prétentieux/inutile/complètement-crétin de vouloir un graphe de dépendances pour les fonctions (sans compter qu'il y a déjà assez de taf comme ça). A voir.
je fais référence au diagramme statique de classe UML:
http://fr.wikipedia.org/wiki/Diagramme_de_classes
je ne suis pas un utilisateur de doxygen, mais imagine, des gens ont un module documenté avec des tags doxygen et ils veulent pouvoir changer d'outil de création de doc. je ne pense pas qu'ils fassent l'effort de changer les "docstring" de toutes leurs sources
Merci pour cette précision.Au passage, je me dit qu'en créant le graphe des dépendances on pourrait aussi fournir automatiquement les appels cycliques. Je garde cela sous le coude.
C'est vrai mais ce genre de chose peut arriver en second. Je vais d'abord avoir une attitude égoïste. De plus, il faudra voir s'il y a une compatibilité avec mon système de documentation sur le fond. De toute façon, je vais parcourir Doxygen à la recherche d'idée. Donc je garde aussi ceci sous le coude.je ne suis pas un utilisateur de doxygen, mais imagine, des gens ont un module documenté avec des tags doxygen et ils veulent pouvoir changer d'outil de création de doc. je ne pense pas qu'ils fassent l'effort de changer les "docstring" de toutes leurs sources
Vous avez un bloqueur de publicités installé.
Le Club Developpez.com n'affiche que des publicités IT, discrètes et non intrusives.
Afin que nous puissions continuer à vous fournir gratuitement du contenu de qualité, merci de nous soutenir en désactivant votre bloqueur de publicités sur Developpez.com.
Répondre avec citation
Partager