Bonsoir,
tout est dans le titre.
Version imprimable
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
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.Citation:
Envoyé par Bayard
On peut faire de petites personnalisations en LaTeX mais cela reste très technique.Citation:
Envoyé par kango
J'irais même jusqu'à pouvoir insérer des petits applets Java dans certaines situations.Citation:
Envoyé par kango
Pas mal d'outils de doc. bute sur ceci. Un outil comme MathJax permet une gestion des formules dans LaTeX et dans le HTML.Citation:
Envoyé par kango
Moi autodidacte, moi pas comprendre...Citation:
Envoyé par kango
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 ?Citation:
Envoyé par kango
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é :mrgreen:.
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.Citation:
Envoyé par nardo47
Moi autodidacte, moi toujours pas comprendre...Citation:
Envoyé par nardo47
C'est ce qui manque à epydoc mais j'avoue que je n'ai pas creusé beaucoup.Citation:
Envoyé par nardo47
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 ?Citation:
Envoyé par nardo47
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...Citation:
Envoyé par nardo47
J'ai pas appris ça à l'école, mais en lisant des docs sur Python.Citation:
Envoyé par rambc
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. :PCitation:
Envoyé par rambc
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 (:P), 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).Citation:
Envoyé par rambc
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:Citation:
Envoyé par rambc
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. :D 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.Citation:
Envoyé par kango
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.Citation:
Envoyé par kango