search

saga-project / bliss

ATTENTION: bliss is now saga-python. Please check out the new project website for the latest version: http://saga-project.github.com/saga-python/
http://saga-project.github.com/saga-python/
Other
8 stars 4 forks source link

API Documentation Broken #81

Closed oweidner closed 12 years ago

oweidner commented 12 years ago

Recently, epydoc is having issues with generating the API documentation. Every module appears twice in the generated HTML.


Warning: Module bliss.saga.Context is shadowed by a variable with the same name.
Warning: Module bliss.saga.Error is shadowed by a variable with the same name.
Warning: Module bliss.saga.Exception is shadowed by a variable with the same name.
Warning: Module bliss.saga.Object is shadowed by a variable with the same name.
Warning: Module bliss.saga.Session is shadowed by a variable with the same name.
Warning: Module bliss.saga.Url is shadowed by a variable with the same name.
Warning: Module bliss.saga.resource.Compute is shadowed by a variable with the same name.
Warning: Module bliss.saga.resource.ComputeDescription is shadowed by a variable with the same name.
Warning: Module bliss.saga.resource.Manager is shadowed by a variable with the same name.
Warning: Module bliss.saga.resource.State is shadowed by a variable with the same name.
Warning: Module bliss.saga.resource.Storage is shadowed by a variable with the same name.
Warning: Module bliss.saga.resource.StorageDescription is shadowed by a variable with the same name.
andre-merzky commented 12 years ago

Ah: Module Context versus class Context! I bet that, if you rename Context.py to context.py, the problem goes away (for Context)...

oweidner commented 12 years ago

Hm. But it worked just fine in the past… scratch.

On Aug 23, 2012, at 4:13 PM, Andre Merzky notifications@github.com wrote:

Ah: Module Context versus class Context! I bet that, if you rename Context.py to context.py, the problem goes away (for Context)...

— Reply to this email directly or view it on GitHub.

andre-merzky commented 12 years ago

I just tried that, renaming all files and imports. Tedius, but seems to work... Didn't you at some point rename context_api.py to Context.py, etc?

andre-merzky commented 12 years ago

Ole, I have the rename Context.py -> context.py etc. done, and it seems to work. Do you want me to commit that? I am sure it will break BigJob :-P

bigjob/bigjob_manager.py:import bliss.saga.job.Description

A.

andre-merzky commented 12 years ago

Sorry, could not resist posting that conundrum to the mailing list, as you will well appreciate ;-)

oweidner commented 12 years ago

Ok, so after some experimentation, I discovered the following completely by accident: If epydoc is installed in the same virtualenv in which bliss is installed and if that virtualenv is active at the time of documentation generation, you end up with that weird error.

If epydoc is part of the 'system' python, i.e., 'sudo pip install epydoc' and not in virtulenv, the problem doesn't show up.

Obviously, this is completely beyond my comprehension. But then, I don't really care as long as it works ;-) I have re-generated the API documentation and it looks just fine: http://saga-project.github.com/bliss/apidoc/

andre-merzky commented 12 years ago

Hi Ole,

I am glad that works for you again. Alas, it does not so for me. I am not using virtualenv at all, so your resolution does not really apply. Also, bliss is not installed along with epydoc in system space::

merzky@thinkie:~/saga/bliss (master %) $ which epydoc
/usr/bin/epydoc
merzky@thinkie:~/saga/bliss (master %) $ which python
/usr/bin/python
merzky@thinkie:~/saga/bliss (master %) $ find /usr/lib/python* -name
bliss -type d
merzky@thinkie:~/saga/bliss (master %) $ find /usr/lib/python* -name
saga -type d
merzky@thinkie:~/saga/bliss (master %) $ find /usr/lib/python* -name
Context.py -type d
merzky@thinkie:~/saga/bliss (master %) $ echo $PYTHONPATH
:/home/merzky/saga/install//lib/python2.6/site-packages:/usr/local/lib/python2.6/site-packages/:/home/merzky/saga/install//lib/python2.6/site-packages:/usr/local/lib/python2.6/site-packages/
merzky@thinkie:~/saga/bliss (master %) $ cd
merzky@thinkie:~ $ python -c 'import bliss'
Traceback (most recent call last):
  File "<string>", line 1, in <module>
ImportError: No module named bliss

As said earlier, the problem seems to appear with revision 9b79baf9b43d4b4f891444c27465620ca6e2c3fe for me.

So, unless we find a fix (or merge from feature/documentation_fix), generating the API documentation will be your task ;-) But I would prefer that getting fixed reliably...

oweidner commented 12 years ago

Hi Andre,

I have generated the API numerous times after that commit and the problem has never shown up. I am hesitant to merge your branch since it will break dependent software. I'm fine with generating the API documentation on my machine if it doesn't work on yours.

On Aug 24, 2012, at 2:31 PM, Andre Merzky notifications@github.com wrote:

As said earlier, the problem seems to appear with revision 9b79baf for me.

andre-merzky commented 12 years ago

Ok, as long as your are fine updating the documentation now and then, I don't mind.

Thanks, Andre.

oweidner commented 12 years ago

Sure. That's part of the release protocol anyways: https://github.com/saga-project/bliss/wiki/Create-a-Release

On Aug 24, 2012, at 2:41 PM, Andre Merzky notifications@github.com wrote:

Ok, as long as your are fine updating the documentation now and then, I don't mind.

Thanks, Andre.

— Reply to this email directly or view it on GitHub.