Discussion :

[deusyss]

Bonjour à tous,

Je vous invite à découvrir l'outil de documentation Sphinx grâce à cet article.

Bonne lecture à tous

[Luke spywoker]

Salut deusyss,

j'ai parcourus ton tutoriel et moi qui croyais presque tout savoir sur sphinx (ayant lu attentivement la documentation officiel) je suis étonner de ce que j'ai découvert dans ton tutoriel.

Je vais me l'imprimer, le lire complètement et l'archiver avec mes autres tutoriels.

Encore une fois du beau travail et grand merci au nom de la communauté python envers laquelle ton dévouement est admirable.

Si je puis me permettre, j'ai écrit un tutoriel sur les bases de la programmation 3D avec (py)OpenGL générer avec sphinx, sous forme de pages *.html, dont vous pouvez regarder le rendu et les sources (En ReST) sont compris dans le zip, si ça peut vous aider.

Bonne continuation.

[deusyss]

Bonjour Luke,

Merci beaucoup pour ton retour. Effectivement ta documentation est un très bon exemple de rendu. Et le sujet est intéressant en plus.

Heureux de t'avoir permis d'apprendre encore un peu plus, et de te voir de retour

[Luke spywoker]

Pour ceux que ça intéresse j'aimerai soulever les points suivant en complément:

En tant que python je conseille vivement le ReST car il permet de générer des documents dans divers formats (*pdf, *.html, Latex, et même des manpages) d'après une syntaxe ultra simple, grâce a des outils comme:
rst2pdf,
rst2html,
rst2man
et sphinx qui regroupes ces formats de sorties comme préciser dans le tutoriel de deusyss mais la sortie et les possibilités de configuration sont différentes.

Et puis le ReST est le langage de documentation officiel par convention de python:
pour preuve le documentation officiel de python est générer avec le ReST et sphinx.

Il existe sous Linux un éditeur spécialiser dans le ReST et MarkDown qui s'appelle ReText.
Qui permet d'écrire du ReST, d'avoir un aperçu en HTML et des traceback en cas d'erreur (mécanique que sphinx pourvoie aussi).

Le ReST ou le MarkDown peuvent tous les deux êtres utilisés pour créer la page d'accueil de vos projets déposer sur github en tant que readme.rst (ReST) ou readme.md (MarkDown).


Le ReST peut également être utiliser pour créer la page d'accueil de vos modules sur PyPI (Python Package Index) en fournissant un document au format ReST comme argument de description longue comme expliquer dans mon tutoriel intituler: Uploader un module sur PyPI avec distutils document générer avec rst2pdf.


Pour avoir un aperçus du rendus:

rendez-vous a la page de mon module pyglut (module d'aide a la programmation 3D avec pyopengl) sur PyPI.

Ou sur la page github de pyglut dont la documentation est également générée avec sphinx, avec un index et une mécanique de recherches, le tout grâce a sphinx.

[deusyss]

Salut Luke,

Merci beaucoup pour ces petite precision, et ce logiciel que je ne connaissais pas

[Lana.Bauer]

Félicitations !

[deusyss]

Merci

[MaitrePylos]

Aujourd'hui je me dit bon allez je me met à Sphinx pour mon projet de doc et voila le tuto dont je rèvais

Merci.

[deusyss]

De rien, heureux que cela plaise.

Petite info complémentaire: si j'explique comment autodocumenter son code avec Python, il faut savoir que cela est a priori aussi possible avec d'autre langage. Mais je ne suis pas catégorique, n'ayant jamais essayé.

[deusyss]

Je me permets de signaler, parmi les nombreuses directives existantes et non abordées dans ma doc, l'existance de ".. versionadded:: X.X.X".

J'ai eu à utiliser cela dans mon travail récemment, après que l'article soit publié

Cela peux toujours servir