Re: Epydoc failed to generate documentation for Django 1.5

2013-04-04 Thread Reinout van Rees 

On 04-04-13 05:19, Kevin Veroneau wrote:


| Import failed (but source code parsing was successful).
| Error: ImproperlyConfigured: Requested setting DATABASES, but
settings are not configured.
|You must either define the environment variable
DJANGO_SETTINGS_MODULE or call
|settings.configure() before accessing settings. (line 1)



Is this Epydoc error related to Epydoc or something that Django
shouldn't have done in it's source code?


I first thought "isn't this just the common problem of needing to set 
DJANGO_SETTINGS_MODULE?". I have to do it all the time in my own sphinx 
documentation. A quick os.environ call from sphinx' conf.py fixes that.


Looking at the code of the management command that epydoc crashes on, it 
seems that epydoc simply executes too much. This might be one of the 
cases where there's no handy way of supporting such an introspective tool.


Can you ignore files in epydoc?


Reinout

--
Reinout van Reeshttp://reinout.vanrees.org/
rein...@vanrees.org http://www.nelen-schuurmans.nl/
"If you're not sure what to do, make something. -- Paul Graham"

--
You received this message because you are subscribed to the Google Groups "Django 
developers" group.
To unsubscribe from this group and stop receiving emails from it, send an email 
to django-developers+unsubscr...@googlegroups.com.
To post to this group, send email to django-developers@googlegroups.com.
Visit this group at http://groups.google.com/group/django-developers?hl=en.
For more options, visit https://groups.google.com/groups/opt_out.

Re: Epydoc failed to generate documentation for Django 1.5

2013-04-03 Thread Kevin Veroneau 
Take a look at the generic views auto-generated docs from Epydoc(link in my 
post), it's definitely breathtaking.  Especially seeing how all the classes 
come together in a nice UML graph.  It really provides some prospective on 
how hard the core Django developer work and think over a process like CRUD 
and how to make it extendable.  it uses docstrings, which provide 
additional info on the classes and methods themselves.

On Wednesday, 3 April 2013 22:26:06 UTC-5, Jacob Kaplan-Moss wrote:
>
> On Wed, Apr 3, 2013 at 10:19 PM, Kevin Veroneau 
>  
> wrote: 
> > Is this Epydoc error related to Epydoc or something that Django 
> shouldn't 
> > have done in it's source code? 
>
> It looks perhaps like something you'd need to fix -- the message about 
> settings.configure() indicates that you're loading code that requires 
> settings, but you haven't configured them -- but it's really hard to 
> say. 
>
> Ultimately though I think if you want to do this it's probably going 
> to be on you; I'd be quite against making any changes to Django to 
> accommodate tools like Epydoc. I'm quite skeptical about the value 
> that auto-generated documentation provides, so I'm going to encourage 
> any effort spent on documentation to be spent writing prose, not 
> trying to trick a machine into writing prose. 
>
> Jacob 
>

-- 
You received this message because you are subscribed to the Google Groups 
"Django developers" group.
To unsubscribe from this group and stop receiving emails from it, send an email 
to django-developers+unsubscr...@googlegroups.com.
To post to this group, send email to django-developers@googlegroups.com.
Visit this group at http://groups.google.com/group/django-developers?hl=en.
For more options, visit https://groups.google.com/groups/opt_out.

Re: Epydoc failed to generate documentation for Django 1.5

2013-04-03 Thread Jacob Kaplan-Moss 
On Wed, Apr 3, 2013 at 10:19 PM, Kevin Veroneau  wrote:
> Is this Epydoc error related to Epydoc or something that Django shouldn't
> have done in it's source code?

It looks perhaps like something you'd need to fix -- the message about
settings.configure() indicates that you're loading code that requires
settings, but you haven't configured them -- but it's really hard to
say.

Ultimately though I think if you want to do this it's probably going
to be on you; I'd be quite against making any changes to Django to
accommodate tools like Epydoc. I'm quite skeptical about the value
that auto-generated documentation provides, so I'm going to encourage
any effort spent on documentation to be spent writing prose, not
trying to trick a machine into writing prose.

Jacob

-- 
You received this message because you are subscribed to the Google Groups 
"Django developers" group.
To unsubscribe from this group and stop receiving emails from it, send an email 
to django-developers+unsubscr...@googlegroups.com.
To post to this group, send email to django-developers@googlegroups.com.
Visit this group at http://groups.google.com/group/django-developers?hl=en.
For more options, visit https://groups.google.com/groups/opt_out.

Epydoc failed to generate documentation for Django 1.5

2013-04-03 Thread Kevin Veroneau 
Hello Django team,

  I was attempting to build documentation for Django 1.5, and it seems that 
Epydoc doesn't like something in the GIS contrib in the tests.py module.  
Here is the beginning of the error, see the attached text file for the full 
stacktrace:

| In 
/home/kveroneau/django15-env/lib/python2.6/site-packages/django/contrib/gis/management/
| commands/inspectdb.py:
| Import failed (but source code parsing was successful).
| Error: ImproperlyConfigured: Requested setting DATABASES, but 
settings are not configured.
|You must either define the environment variable 
DJANGO_SETTINGS_MODULE or call 
|settings.configure() before accessing settings. (line 1)
|   
  Error: Internal error during parsing 
(/home/kveroneau/django15-env/lib/python2.6/
 site-packages/django/contrib/gis/tests/__init__.py, line 84):
 'int' object is unsubscriptable

  I was able to successfully map out the generic class-based views with UML 
graphs too, you can see it live here:

http://epydoc.pythondiary.com/generic-views/

It really shows the complexity behind some of the class-based views Django 
has.  The next thing I wanted to attempt is to document the entire Django 
project using Epydoc to see how that would look.  Seeing these UML graphs 
is memorizing and very educational for when working with Django.

Is this Epydoc error related to Epydoc or something that Django shouldn't 
have done in it's source code?

Best Regards,
  Kevin Veroneau

-- 
You received this message because you are subscribed to the Google Groups 
"Django developers" group.
To unsubscribe from this group and stop receiving emails from it, send an email 
to django-developers+unsubscr...@googlegroups.com.
To post to this group, send email to django-developers@googlegroups.com.
Visit this group at http://groups.google.com/group/django-developers?hl=en.
For more options, visit https://groups.google.com/groups/opt_out.


  Error: Internal error during parsing 
(/home/kveroneau/django15-env/lib/python2.6/
 site-packages/django/contrib/gis/tests/__init__.py, line 84):
 'int' object is unsubscriptable
Traceback (most recent call last):
  File "/home/kveroneau/django15-env/bin/epydoc", line 13, in 
cli()
  File 
"/home/kveroneau/django15-env/lib/python2.6/site-packages/epydoc/cli.py", line 
965, in cli
main(options, names)
  File 
"/home/kveroneau/django15-env/lib/python2.6/site-packages/epydoc/cli.py", line 
757, in main
exclude_parse=exclude_parse)
  File 
"/home/kveroneau/django15-env/lib/python2.6/site-packages/epydoc/docbuilder.py",
 line 206, in build_doc_index
doc_pairs = _get_docs_from_items(items, options)
  File 
"/home/kveroneau/django15-env/lib/python2.6/site-packages/epydoc/docbuilder.py",
 line 398, in _get_docs_from_items
item, doc_pairs[-1], options, progress_estimator)
  File 
"/home/kveroneau/django15-env/lib/python2.6/site-packages/epydoc/docbuilder.py",
 line 602, in _get_docs_from_submodules
subpackage_dir, docs[-1], options, progress_estimator)
  File 
"/home/kveroneau/django15-env/lib/python2.6/site-packages/epydoc/docbuilder.py",
 line 602, in _get_docs_from_submodules
subpackage_dir, docs[-1], options, progress_estimator)
  File 
"/home/kveroneau/django15-env/lib/python2.6/site-packages/epydoc/docbuilder.py",
 line 600, in _get_docs_from_submodules
subpackage_file, options, progress_estimator, pkg_docs))
  File 
"/home/kveroneau/django15-env/lib/python2.6/site-packages/epydoc/docbuilder.py",
 line 549, in _get_docs_from_module_file
filename=filename, context=parent_docs[1])
  File 
"/home/kveroneau/django15-env/lib/python2.6/site-packages/epydoc/docparser.py", 
line 278, in parse_docs
process_file(module_doc)
  File 
"/home/kveroneau/django15-env/lib/python2.6/site-packages/epydoc/docparser.py", 
line 631, in process_file
lineno, comments, decorators, encoding)
  File 
"/home/kveroneau/django15-env/lib/python2.6/site-packages/epydoc/docparser.py", 
line 756, in process_line
return process_classdef(*args)
  File 
"/home/kveroneau/django15-env/lib/python2.6/site-packages/epydoc/docparser.py", 
line 1549, in process_classdef
class_doc.bases.append(find_base(base_name, parent_docs))
  File 
"/home/kveroneau/django15-env/lib/python2.6/site-packages/epydoc/docparser.py", 
line 1624, in find_base
return parse_docs(name=str(base_var.imported_from))
  File 
"/home/kveroneau/django15-env/lib/python2.6/site-packages/epydoc/docparser.py", 
line 219, in parse_docs
val_doc = _find(name)
  File 
"/home/kveroneau/django15-env/lib/python2.6/site-packages/epydoc/docparser.py", 
line 393, in _find
return _find(name[1:], module_doc)
  File 
"/home/kveroneau/django15-env/lib/python2.6/site-packages/epydoc/docparser.py", 
line 393, in _find
return _find(name[1:], module_doc)
  File 
"/home/kveroneau/django15-env/lib/python2.6/site-packages/epydoc/docparser.py", 
line 378, in _find
module_doc = parse_docs(filename,