{Sphinx + Django} Impossible d'autodocumenter mon code

Version imprimable

Bonjour :) !

Bon, me voila totalement bloqué dans l’auto-documentation de mon code Python dans le cadre d'un projet Django.

Ma situation est la suivante: Travaillant sur un projet Django qui commence a accumuler un bon nombres de lignes de code. J'ai décider de créer une doc technique afin de faciliter le travail de compréhension de mon code a un ami qui doit bientot venir travailler lui aussi sur le projet.
Le seul problème c'est que quel que soit la méthode que j'utilise, il m'est impossible d'arriver a autodocumenter mon code (récupérer les docstrings de mes modules, fonctions, classes etc .. ). Quoi que je fasse je me retrouve avec une liste de messages d'erreurs incompréhensibles.

Mon projet se présente sous cette forme :
.
├── cta_proposal_handling
├── Docs
│** ├── build
│** │** ├── doctrees
│** │** └── html
│** │** ├── _sources
│** │** └── _static
│** └── source
│** ├── _static
│** └── _templates
├── proposal
| |____views.py
| |______init__.py
| |____forms.py
| |____etc..
├── static
│** ├── css
│** ├── fonts
│** ├── images
│** └── js
├── templates
| |___*.html
│** └── backup
└── webportal

l'index de ma doc (index.rst) :

Code:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
 
.. CTA_Documentation documentation master file, created by                                                           
   sphinx-quickstart on Thu Aug 27 20:13:12 2015.                                                                    
   You can adapt this file completely to your liking, but it should at least                                         
   contain the root `toctree` directive.                                                                             
 
Welcome to CTA_Documentation's documentation!
=============================================
 
Contents:
 
.. toctree::
   :maxdepth: 5
 
  Page0
  Page1
  Page2
  Page3
  Page4
 
 
Indices and tables
==================
 
* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`

La page ou est censée se trouver l'auto documentation:

Code:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
 
******************************************************
Descriptif des vues et et formulaires/modeles associes
******************************************************
 
I-Pour les views:
-----------------
 
.. automodule::	views.py
 
II-Pour les forms:
------------------
 
.. autoclass:: forms.py
    :members:
 
III-Pour les models
-------------------
 
.. autoclass:: models.py
    :members:

Mon conf.py ( la partie avec les insert)

Code:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
 
# -*- coding: utf-8 -*-                                                                                              
#                                                                                                                    
# CTA_Documentation documentation build configuration file, created by                                               
# sphinx-quickstart on Thu Aug 27 20:13:12 2015.                                                                     
#                                                                                                                    
# This file is execfile()d with the current directory set to its containing dir.                                     
#                                                                                                                    
# Note that not all possible configuration values are present in this                                                
# autogenerated file.                                                                                                
#                                                                                                                    
# All configuration values have a default; values that are commented out                                             
# serve to show the default.                                                                                         
 
import sys, os
 
# If extensions (or modules to document with autodoc) are in another directory,                                      
# add these directories to sys.path here. If the directory is relative to the                                        
# documentation root, use os.path.abspath to make it absolute, like shown here.                                      
sys.path.insert(0, os.path.abspath('../../proposal'))
sys.path.insert(0, os.path.abspath('../../webportal'))

Et enfin ce que j'ai rajouté dans le __init.py__ du dossier proposal: (suite au tuto http://deusyss.developpez.com/tutori...#LV-B-1http:// )

Code:

1
2
3
4
5
 
" »                                                                                                                   
.. automodule:: proposal.views                                                                                        
   :members:                                                                                                          
« "

Voila. Et quand avec tout ca je fais un 'make html' je me retrouve avec les warning :

Code:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
 
sphinx-build -b html -d build/doctrees   source build/html
Running Sphinx v1.1.3
loading pickled environment... done
building [html]: targets for 1 source files that are out of date
updating environment: 0 added, 2 changed, 0 removed
Traceback (most recent call last):                                                                                   
  File "/usr/lib/python2.7/site-packages/sphinx/ext/autodoc.py", line 321, in import_object
    __import__(self.modname)
  File "/home/meuric_a/cta_proposal_handling_save--crash_home--/webportal/views.py", line 7, in <module>
    from webportal.forms import NewUserForm
ImportError: No module named webportal.forms
Traceback (most recent call last):
  File "/usr/lib/python2.7/site-packages/sphinx/ext/autodoc.py", line 321, in import_object
    __import__(self.modname)
  File "/home/meuric_a/cta_proposal_handling_save--crash_home--/webportal/forms.py", line 5, in <module>
    from models import User
  File "/home/meuric_a/cta_proposal_handling_save--crash_home--/webportal/models.py", line 7, in <module>
    class User(models.Model):
  File "/home/meuric_a/cta_proposal_handling_save--crash_home--/webportal/models.py", line 12, in User
    userID    = models.AutoField(primary_key=True)
  File "/usr/lib/python2.7/site-packages/Django-1.8.3-py2.7.egg/django/db/models/fields/__init__.py", line 931, in __init__
    super(AutoField, self).__init__(*args, **kwargs)
  File "/usr/lib/python2.7/site-packages/Django-1.8.3-py2.7.egg/django/db/models/fields/__init__.py", line 161, in __init__
    self.db_tablespace = db_tablespace or settings.DEFAULT_INDEX_TABLESPACE
  File "/usr/lib/python2.7/site-packages/Django-1.8.3-py2.7.egg/django/conf/__init__.py", line 48, in __getattr__
    self._setup(name)
  File "/usr/lib/python2.7/site-packages/Django-1.8.3-py2.7.egg/django/conf/__init__.py", line 42, in _setup
    % (desc, ENVIRONMENT_VARIABLE))
ImproperlyConfigured: Requested setting DEFAULT_INDEX_TABLESPACE, but settings are not configured. You must either define the environment variable DJANGO_SETTINGS_MODULE or call settings.configure() before accessing settings.
Traceback (most recent call last):
  File "/usr/lib/python2.7/site-packages/sphinx/ext/autodoc.py", line 321, in import_object
    __import__(self.modname)
  File "/home/meuric_a/cta_proposal_handling_save--crash_home--/webportal/models.py", line 7, in <module>
    class User(models.Model):
  File "/home/meuric_a/cta_proposal_handling_save--crash_home--/webportal/models.py", line 12, in User
    userID    = models.AutoField(primary_key=True)
  File "/usr/lib/python2.7/site-packages/Django-1.8.3-py2.7.egg/django/db/models/fields/__init__.py", line 931, in __init__
    super(AutoField, self).__init__(*args, **kwargs)
  File "/usr/lib/python2.7/site-packages/Django-1.8.3-py2.7.egg/django/db/models/fields/__init__.py", line 161, in __init__
    self.db_tablespace = db_tablespace or settings.DEFAULT_INDEX_TABLESPACE
  File "/usr/lib/python2.7/site-packages/Django-1.8.3-py2.7.egg/django/conf/__init__.py", line 48, in __getattr__
    self._setup(name)
  File "/usr/lib/python2.7/site-packages/Django-1.8.3-py2.7.egg/django/conf/__init__.py", line 42, in _setup
    % (desc, ENVIRONMENT_VARIABLE))
ImproperlyConfigured: Requested setting DEFAULT_INDEX_TABLESPACE, but settings are not configured. You must either define the environment variable DJANGO_SETTINGS_MODULE or call settings.configure() before accessing settings.
reading sources... [100%] index                                                                                      
/home/meuric_a/cta_proposal_handling_save--crash_home--/Docs/source/Page4.rst:8: WARNING: autodoc can't import/find module 'views.py', it reported error: "No module named webportal.forms", please check your spelling and sys.path
/home/meuric_a/cta_proposal_handling_save--crash_home--/Docs/source/Page4.rst:13: WARNING: autodoc can't import/find class 'forms.py', it reported error: "Requested setting DEFAULT_INDEX_TABLESPACE, but settings are not configured. You must either define the environment variable DJANGO_SETTINGS_MODULE or call settings.configure() before accessing settings.", please check your spelling and sys.path
/home/meuric_a/cta_proposal_handling_save--crash_home--/Docs/source/Page4.rst:19: WARNING: autodoc can't import/find class 'models.py', it reported error: "Requested setting DEFAULT_INDEX_TABLESPACE, but settings are not configured. You must either define the environment variable DJANGO_SETTINGS_MODULE or call settings.configure() before accessing settings.", please check your spelling and sys.path
/home/meuric_a/cta_proposal_handling_save--crash_home--/Docs/source/index.rst:11: WARNING: toctree contains reference to nonexisting document u' :maxdepth: 5'
looking for now-outdated files... none found
pickling environment... done
checking consistency... done
preparing documents... done
writing output... [100%] index                                                                                       
writing additional files... (0 module code pages) genindex search
copying static files... done
dumping search index... done
dumping object inventory... done
build succeeded, 4 warnings.
 
Build finished. The HTML pages are in build/html.

DOnc toutes mes pages sont générées comme je le voulais, sauf l'autodoc qui n'apparait nul part.. Ce qui est je suppose liée a tout ces messages d'erreurs mais dont je ne comprends pas vraiment les signification.

Alors si quelqu'un ( mon heros) pouvait prendre le temps de m'expliquer ce que je fais de mal et comment récupérer mes Docstrings pour générer l'autodocumentation, je lui serais infiniment reconnaissant.

Salut,

Code:

1
2
3
ImproperlyConfigured: Requested setting DEFAULT_INDEX_TABLESPACE, but settings are not 
configured. You must either define the environment variable DJANGO_SETTINGS_MODULE or
call settings.configure() before accessing settings.

Ce qui dans la pratique passe par ajouter:

Code:

1
2
from django.conf import settings
settings.configure()

dans le conf.py.

- W

02/09/2015, 14h17
123alban2007

Oki, voila un problème idiot de régler. Merci :) !

Cependant .. Il en reste pas mal d'autres notamment des problèmes d'import ( from ... import ..).

Ce qui est logique, car Django ne gere pas les imports de la meme facon que le fait Python. Malheureusement, je me pose maintentant la question, Sphinx pour génerer de la Doc n'a t'il pas besoin d'un code Python "Fonctionnel" ? :/

Si oui, il est normal que la génération de ma Documentation ne marche pas. Et il est aussi normal que Sphinx me crache des messages d'erreurs..

Malgré cela, mon code est tout de meme fonctionnel pour Django et j'ai toujours besoin de le documenter. Alors comment faire ?

Pensez vous qu'il y'a moyen de contourner ce problème d'import grâce a "mock" ?

Ou avez vous une autre idée ?

Je ne pensais pas que documenter un code Django me poserait tant de soucis, c'est presque plus difficile que de coder avec Django X) ! Si jamais quelqu'un a déja travaillé sur ce Framework et réalisé une doc je serais intéressés de savoir si il a rencontré les mêmes problèmes que moi et qu'elle solution technique il a choisi ^^.
02/09/2015, 19h30
deusyss

Bonsoir,

Ce serait à verifier, mais normalement, Sphinx ne fait pas appel à Python. Le code est donc uniquement lu par Sphinx qui interprete les commandes specifique afin de construire la documentation.

Tu parles de messages d'erreur. Il serait bon de nous les communiquer afin que nous puissions mieux t'aider.

Cas échéant, si cela pose des soucis (code confidentiel, ou autre), essai d'inclure dasn ta doc, module par module, ce que tu souhaite documenter. Cela te permettra alors d'isoler ce qui pose soucis.
02/09/2015, 20h11
wiztricks

Salut,

Citation:

Envoyé par deusyss

Ce serait à verifier, mais normalement, Sphinx ne fait pas appel à Python. Le code est donc uniquement lu par Sphinx qui interprete les commandes specifique afin de construire la documentation.

extrait de la documentation:

Citation:

Note
For Sphinx (actually, the Python interpreter that executes Sphinx) to find your module, it must be importable. That means that the module or the package must be in one of the directories on sys.path – adapt your sys.path in the configuration file accordingly.

Citation:

Envoyé par 123alban2007

Ce qui est logique, car Django ne gere pas les imports de la meme facon que le fait Python. Malheureusement, je me pose maintentant la question, Sphinx pour génerer de la Doc n'a t'il pas besoin d'un code Python "Fonctionnel" ? :/

"fonctionnel", non... mais que l'on puisse importer pour permettre de construire un arbre avec les différentes déclarations. De plus, pas facile d'écrire son code et ses docstrings n'importe comment pour que Sphinx s'y retrouve. Mais comme de nombreux projets utilisent Sphinx, çà fait autant de "codes" à regarder pour voir comment les développeurs s'en sont sorti (Python, sqlalchemy,...).
- W
03/09/2015, 07h24
deusyss

Citation:

Envoyé par wiztricks

"fonctionnel", non... mais que l'on puisse importer pour permettre de construire un arbre avec les différentes déclarations. De plus, pas facile d'écrire son code et ses docstrings n'importe comment pour que Sphinx s'y retrouve. Mais comme de nombreux projets utilisent Sphinx, çà fait autant de "codes" à regarder pour voir comment les développeurs s'en sont sorti (Python, sqlalchemy,...).
- W

Très bonne remarque. Internet ne manque pas d'exemple, Sphinx étant devenu l'outil officiel de documentation Python il y a plusieurs années.
07/09/2015, 14h46
123alban2007

Re-Bonjour

Désolé je n'ai pas vraiment suivi la conversation. J'ai crasher OpenSuse du coup je suis passer a manjaro et j'ai du réinstaller tout mon pc dans le weekend c'etait un peu la galere, bref.

Alors, je n'ai pas réussi a trouver d'exemples parlant d'autodocumentation, mais en bricolant un petit peu j'ai réussi a génerer mon autodocumentation meme si pour l'instant mon travail ne me satisfait pas :/

Cependant un autre probleme qui lui aussi me pose quand même un petit soucis et je pense pourrait intéresser d'autres dev' Django ma sauté aux yeux il y'a peux.

Je m'explique:

Pour l'auto-documentation (dans le cas présent, automodule), sphinx cherche le module du nom renseigné apres 'automodule'. A partir des chemins renseignés dans conf.py; sys.path.insert......

Cependant pour un projet Django si l'on cherche a autodocumenter un module tel que views.py un probleme se pose.

En effet, un projet Django se divise en plusieurs 'applications'. L'application X, L'appli Y ...etc . Et pour chaque application, on retrouvera les fichiers views.py forms.py modules.py etc ...

Chaque appli etant regroupée dans un fichier, il faudra renseigné plusieurs chemins dans conf.py avec sys.path.insert.

Et pour autodocumenter mes views.py je procede ainsi : .. automodule:: views

Le probleme etant que avec cette syntaxe, Sphinx va autodocumenter le views.py du dernier sys.path.insert et pas les views.py accesible par les autres sys.path.insert :/

Alors pensez vous qu'il y a une solution a ceci ? Peut on indiquer a Sphinx précisément quel module documenter ?

( Je ne sais pas si mes explications sont toutes a fait compréhensible :/ )
07/09/2015, 19h18
wiztricks
Citation:

Envoyé par 123alban2007

Alors pensez vous qu'il y a une solution a ceci ? Peut on indiquer a Sphinx précisément quel module documenter ?

Ce qui nous ramène à la case de départ:
Code:

1 2 You must either define the environment variable DJANGO_SETTINGS_MODULE or call settings.configure() before accessing settings.
...mais... il faut prendre la branche "DJANGO_SETTINGS_MODULE" sans oublier que lorsque vous "construisez" la documentation vous n'êtes pas en "prod" mais en "dev". Ce qui permet quelques libertés côté "setting".

note: pourquoi produire des documentations si vous ne lisez pas les documents déjà existants?

- W
08/09/2015, 18h04
123alban2007

Alors alors,

Je crois déceler une légère animosité dans ce dernier message.

Senpai j'ai commencé Django il n'ya meme pas un mois et Sphinx il y'a une semaine vu le nombre incalculable de pages de docs que j'ai eu l'occasion de lire durant ce laps de temps, il n'est pas étonnant que certaines choses m'échappe ...

D'ailleurs sur ce que j'ai compris du fonctionnement des Settings de Django, j'ai du mal a visualiser comment j'aurais pu m'en servir afin de faire comprendre a Sphinx que je voulais documenter les fichiers du meme nom dans deux dossiers differents. Si jamais vous vous etiez déja retrouvé dans cette situation je serais intéréssé de savoir comment vous avez réussi a vous débrouiller.

Bref, J'ai tout de même trouvvé la solution et elle est vraiment bête.

Les deux dossiers contenant les fichiers que je voulais autodocumenter se trouvant eux meme dans le meme dossier. Il m'a suffit d'inclure dans le sys.path.... de conf.py le chemin vers le dossier parent au deux dossier contenant mon code. Puis du coté de Sphinx en ReST :

.. automodule:: lechemivers.monfichier.py

.. automodule:: autrecheminvers.monautrefichier.py

Voila voila, peut etre que ca pourra en aider certains ;) !