Discussion :

[Narann]

Bonjours a tous!

J'ai passe ma soire hier a essayer de trouver comment définir, dans sphinx le dossier ou sont place les sources, celui a parcourir lors de la génération de la doc.

Je m'explique:

Il y a du code python dans un dossier pour lequel je n'ai que les accès en écriture.

J'ai donc utilise sphinx-quickstart pour générer un dossier qui va recevoir ma doc, disons "outputDoc".

Mais j'ai la sensation que c'est le dossier "_source" qui doit contenir le code. Enfin que le dossier du code python a documenter doit contenir le fichier conf.py et index.rst.

Je trouve ça un peu gênant typiquement dans le cas ou le code a documenter n'est pas accessible en écriture (j’essaie de faire une version sphinx de la doc pour leur vendre le truc en fait).

Avec Doxygen je n'ai aucun soucis. Je défini le dossier Include qui contient les fichiers a documenter et c'est tout! Je lance doxygen avec le fichier de config et ça marche.

Je sais que Sphinx permet de mieux gérer le template mais ma question est la suivante:

Il y a t'il un moyen, avec Sphinx, de documenter le code d'un dossier sans avoir a y mettre d'autres fichiers directement dedans? J'ai chercher partout sur le net et impossible de trouver un mec qui a le même soucis que moi...

Merci d'avance pour vos réponses.

[wiztricks]

Bonsoir,

Je suis désolé mais je ne vois pas trop quel est le problème.
Par contre, je sais que lorsque je me suis mis à Sphinx j'ai bien pataugé car beaucoup de choses tombent magiquement en marche pourvu qu'on ne s'éloigne pas trop de ce que la configuration par défaut attend.

Note: Je ne dis pas que ce n'est pas "customisable", juste qu'au démarrage... on a quelques difficultés à appréhender les implications de...

Je vous suggère la lecture 'un tuto' qui m'a bien aidé:
an_example_pypi_project

Après récupérez les sources de projets documentés avec Sphinx (Python, Sphynx, ... il y en a plein) et regardez comment ils ont structurés leurs répertoires.

Bon courage,
- W

[Narann]

Hello et merci pour la réponse.

J'ai déjà regardé les liens que tu m'a donné et il ne m'ont pas donné de réponses (mais merci quand même).

Sphinx se base bien sur du code python? Il parse des fichiers .py non? Comme la plupart des générateurs de documentation.

Doxygen on lui donne le chemin des fichiers a parser:

http://www.star.bnl.gov/public/comp/...html#cfg_input

Ma question est: Ou définir, dans Sphinx, le répertoire des fichiers python à parser?

Ou bien il y a un truc que j'ai vraiment pas compris.

Merci d'avance!

[wiztricks]

Bonsoir,

Sphinx se base bien sur du code python? Il parse des fichiers .py non? Comme la plupart des générateurs de documentation.

Je suis X certain que non mais comme je n'ai jamais eu l'idée d'essayer, X est quasi ou presque.

En fait, Sphinx parse des fichiers .rst (ReST) qui sont écrits en "blocks" comme les scripts Python mais çà n'a rien à voir.

Il sait aussi extraire les "docstrings" d'un script Python (.py) pour inclure les commentaires qu'on a mis dedans (dans la documentation produite) via une extension sphinx.ext.autodoc et les directive auto*.
Note: Cela suppose que ces docstring soient écrites en ReST...

voir http://packages.python.org/an_exampl...l-code-example pour cela.

- W

[Narann]

Ok donc c'est vraiment pas ce que je cherchais en fait...

Bon, merci en tout cas pour les réponses!

[wiztricks]

Salut,


[QUOTE=Narann;6227405]Ok donc c'est vraiment pas ce que je cherchais en fait... [QUOTE]

Je vous avourais que je n'ai pas encore trop compris ce que vous cherchiez à faire.
Doxygen c'est bien et çà permet de générer aussi une documentation à partir de sources Python.
La vocation de Sphynx est similaire (produire des documentations) mais ce n'est pas Doxygen.
- W

[Narann]

Je vous avourais que je n'ai pas encore trop compris ce que vous cherchiez à faire.

Et bien une bête documentation de fonctions pythons en fait.

Mais peut être que je n'ai pas bien compris ce qu'est suppose faire Sphinx...