Discussion :

[123alban2007]

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 :

Sélectionner tout - Visualiser dans une fenêtre à part

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 :

Sélectionner tout - Visualiser dans une fenêtre à part

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 :

Sélectionner tout - Visualiser dans une fenêtre à part

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 :

Sélectionner tout - Visualiser dans une fenêtre à part

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 :

Sélectionner tout - Visualiser dans une fenêtre à part

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.

[wiztricks]

Salut,

Code :

Sélectionner tout - Visualiser dans une fenêtre à part

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 :

Sélectionner tout - Visualiser dans une fenêtre à part

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

dans le conf.py.

- W

[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 ^^.

[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.

[wiztricks]

Salut,

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:

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.

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

[deusyss]

"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.