Pudge troubles

[Stephen F. Steiner]

Hi,

I've been using Pylons for a while but have never any reason to use
pudge for anything until the other day when I needed to take the
Pylons docs on the road with me where I wouldn't have an Iinternet
connection.

I assumed that the HTML documentation for Pylons was built with
pudge but couldn't find any info on how to build the actual
documentation from the sources in the docs directory.

I found the part at http://pylonshq.com/docs/0.9.3/install about using:

easy_install Pylons[pudge]

But using that I get:

Using /Library/Frameworks/Python.framework/Versions/2.5/lib/python2.5/
site-packages/Pylons-0.9.3-py2.5.egg
Processing dependencies for Pylons[pudge]
Searching for buildutils==dev,>=0.1.2dev
Reading http://www.python.org/pypi/buildutils/
Reading http://buildutils.lesscode.org/
Reading http://buildutils.lesscode.org/dist/0.1.1/
Reading http://www.python.org/pypi/buildutils/0.1.1
Best match: buildutils dev
Downloading http://lesscode.org/svn/buildutils/trunk#egg=buildutils-dev
error: Can't download http://lesscode.org/svn/buildutils/trunk: 500
Internal Server Error

Clicking on the pudge 'site' at http://pudge.lesscode.org/, there
are many broken links including the ones to the mailing list at
http://lesscode.org/mailman/listinfo/pudge so there doesn't even seem
to be a mailing list on which to discuss pudge.

Can anyone enlighten me as to the state of pudge and/or the plans
for moving to another documentation system?

Thanks,

S

Stephen F. Steiner
Integrated Development Corporation
sste...@integrateddevcorp.com
www.integrateddevcorp.com
(603)433-1232

[Yury Yurevich]

On 20:59:12 Sun 17 Dec , Stephen F. Steiner wrote:
> easy_install Pylons[pudge]
>
> But using that I get:
>
> Using /Library/Frameworks/Python.framework/Versions/2.5/lib/python2.5/
> site-packages/Pylons-0.9.3-py2.5.egg
> Processing dependencies for Pylons[pudge]
> Searching for buildutils==dev,>=0.1.2dev
> Reading http://www.python.org/pypi/buildutils/
> Reading http://buildutils.lesscode.org/
> Reading http://buildutils.lesscode.org/dist/0.1.1/
> Reading http://www.python.org/pypi/buildutils/0.1.1
> Best match: buildutils dev
> Downloading http://lesscode.org/svn/buildutils/trunk#egg=buildutils-dev
> error: Can't download http://lesscode.org/svn/buildutils/trunk: 500
> Internal Server Error

easy_install -U svn://lesscode.org/buildutils/trunk
easy_install -U svn://lesscode.org/pudge/trunk

[Stephen F. Steiner]

On Dec 17, 2006, at 9:44 PM, Yury Yurevich wrote:

easy_install -U svn://lesscode.org/buildutils/trunk

easy_install -U svn://lesscode.org/pudge/trunk

Thank you but my point was that the pudge section of the Pylons world has not been keeping up-to-date.

[Ben Bangert]

On Dec 17, 2006, at 5:59 PM, Stephen F. Steiner wrote:

> I've been using Pylons for a while but have never any reason to use
> pudge for anything until the other day when I needed to take the
> Pylons docs on the road with me where I wouldn't have an Iinternet
> connection.
>
> I assumed that the HTML documentation for Pylons was built with
> pudge but couldn't find any info on how to build the actual
> documentation from the sources in the docs directory.

Right, there isn't any right now. You'll need builtutils and pudge to
build them. The buildutils link refers to a broken svn repo link,
which needs to be updated (Ian Bicking?). I've updated the pudge link
so that running:
easy_install -U pudge==dev

Now works again. Unfortunately that requires buildutils, which you
can install with:
easy_install -U svn://lesscode.org/buildutils/trunk

That should get you over the hump of installing the necessary tools.

Then, to build the docs, cd to the Pylons source dir and run:
python setup.py pudge

That should build the docs, they will be in docs/html under a few
nested dirs.

> Clicking on the pudge 'site' at http://pudge.lesscode.org/, there
> are many broken links including the ones to the mailing list at
> http://lesscode.org/mailman/listinfo/pudge so there doesn't even seem
> to be a mailing list on which to discuss pudge.

Yes, that's a bit of a bummer, I've been attempting to takeover
maintenance of pudge and have setup a separate trac for it here:
http://pudge.groovie.org/

> Can anyone enlighten me as to the state of pudge and/or the plans
> for moving to another documentation system?

I plan on maintaining pudge for the foreseeable future, or until a
better documentation system comes along that will generate not only
docs from my source code, but separate docs I designate (to my
knowledge, Epydoc doesn't currently do that).

Cheers,
Ben

[Stephen F. Steiner]

On Dec 17, 2006, at 10:02 PM, Ben Bangert wrote:

Can anyone enlighten me as to the state of pudge and/or the plans

for moving to another documentation system?

I plan on maintaining pudge for the foreseeable future, or until a  

better documentation system comes along that will generate not only  

docs from my source code, but separate docs I designate (to my  

knowledge, Epydoc doesn't currently do that).

Cool!  

I'll be following this closely as I think that the documentation part has been somewhat neglected.  

Please let me know where I might be able to help other than the obvious -- following the curent set of instructions and reporting any problems.

Cheers,

S

[Stephen F. Steiner]

On Dec 17, 2006, at 10:02 PM, Ben Bangert wrote:

...

That should get you over the hump of installing the necessary tools.

Ok, got that, all set up, thanks!

Then, to build the docs, cd to the Pylons source dir and run:

python setup.py pudge

That should build the docs, they will be in docs/html under a few  

nested dirs.

Rather than repeat the slew of error messages that produces, see what you get when you try it; maybe I've gotten something wrong.

I corrected them as I went along, but someone with commit access should just work through it to give us a good starting point.

Clicking on the pudge 'site' at http://pudge.lesscode.org/, there

are many broken links including the ones to the mailing list at

http://lesscode.org/mailman/listinfo/pudge so there doesn't even seem

to be a mailing list on which to discuss pudge.

Yes, that's a bit of a bummer, I've been attempting to takeover  

maintenance of pudge and have setup a separate trac for it here:

http://pudge.groovie.org/

Thanks for doing that; I found the trac, how do we actually access the new svn repository?

Can anyone enlighten me as to the state of pudge and/or the plans

for moving to another documentation system?

I plan on maintaining pudge for the foreseeable future, or until a  

better documentation system comes along that will generate not only  

docs from my source code, but separate docs I designate (to my  

knowledge, Epydoc doesn't currently do that).

Cool.  Epydoc doesn't do the same thing at all.  I'm willing to help pudge along as it's entrenched and seems to do the right thing, generally.

I'm thinking that the templates should have the option of Myghty; I'd sure like that better.

Let's get the SVN set up, work through the pudge self-tests, build the Pylons docs without errors, and see where we're at.

Docs are a pain and are absolutely essential; let's work to make them up to the standards of the rest of the project.

I appreciate your efforts on this front.  

Thanks,

S

[James Gardner]

Hi all,

> Let's get the SVN set up, work through the pudge self-tests, build the
> Pylons docs without errors, and see where we're at.

+1, I'm happy to help too.

By the way, I get errors on Windows which don't seem to affect Linux so
if you are using Windows it might be a cause of some of the problems.
Others are probably just typos ;-)

James

[Stephen F. Steiner]

On Dec 17, 2006, at 10:02 PM, Ben Bangert wrote:

I plan on maintaining pudge for the foreseeable future, or until a  

better documentation system comes along that will generate not only  

docs from my source code, but separate docs I designate (to my  

knowledge, Epydoc doesn't currently do that).

Cheers,

Ben

Ben,

I know you're very busy...

Any progress or prognosis for setting up a Pudge SVN?

[Ben Bangert]

On Dec 19, 2006, at 6:22 PM, Stephen F. Steiner wrote:

> I know you're very busy...
>
> Any progress or prognosis for setting up a Pudge SVN?

I'm inclined to keep using the 'official' Pudge SVN for now, as I
have commit access and its still up. I already have another Pudge SVN
setup which I will keep up to date should the official one die at
some point. I'm aiming to actually post a 'release' of Pudge to
CheeseShop soon so people wishing to use it won't have to keep
getting it from svn.

Cheers,
Ben

[Stephen F. Steiner]

Cool, please let me know when you've hit a 'release' and we'll work forward from there.

[Stephen F. Steiner]

On Dec 19, 2006, at 9:36 PM, Ben Bangert wrote:

> I'm inclined to keep using the 'official' Pudge SVN for now, as I
> have commit access and its still up. I already have another Pudge
> SVN setup which I will keep up to date should the official one die
> at some point. I'm aiming to actually post a 'release' of Pudge
> to CheeseShop soon so people wishing to use it won't have to keep
> getting it from svn.

Can we put building the documentation for Pylons with pudge somewhere
in the build procedure so we can make sure it always works?

Right now the i18n doc file throws a few SEVERE/4 error due to tlides
being used in the source instead of dashes.

Here's the first one (after which it dies):

docutils.utils.SystemMessage: docs/internationalization.txt:483:
(SEVERE/4) Title level inconsistent:

Request Parameters
~~~~~~~~~~~~~~~~~~

If you fix that one, it'll happen several more times. Replacing all
of the lines of tildes with lines of dashes solves all of these
problems.

Once all those are all cleaned up, there are several WARNING/2 and
one ERROR/3 in the same file.

Then, with the latest release of Kid (0.9.4) I get:

...

File "/Library/Frameworks/Python.framework/Versions/2.5/lib/python2.5/
site-packages/kid-0.9.4-py2.5.egg/kid/template_util.py", line 120, in
base_class_extends
% (all_extends or extends)).lstrip())
kid.template_util.TemplateExtendsError: Could not open '/Users/
ssteiner/work/Pylons/docs/pudge_template/common.html'
Template file "'common.html'" not found
while processing extends="'layout.html', 'common.html'"

The file's sitting right there so I'm not sure what's up with that...

Trying with the Kid from SVN (453), I get the same doc warnings
followed by:

File "/Library/Frameworks/Python.framework/Versions/2.5/lib/python2.5/
pydoc.py", line 305, in safeimport
raise ErrorDuringImport(path, sys.exc_info())
TypeError: __init__() takes exactly 3 arguments (2 given)

Maybe pudge should be specific about what version of Kid it needs; it
doesn't currently seem to play well with either the release or the
trunk tip revision...

[Ben Bangert]

On Dec 20, 2006, at 6:13 AM, Stephen F. Steiner wrote:

> Can we put building the documentation for Pylons with pudge
> somewhere in the build procedure so we can make sure it always works?
>
> Right now the i18n doc file throws a few SEVERE/4 error due to
> tlides being used in the source instead of dashes.

Yep, I'm seeing it too. I'm currently fixing the docs to get us back
to a point where I can build them all, since I'll need to do that for
the upcoming release. :) You'll see some commits go by today as I fix
these.

Cheers,
Ben

[Ben Bangert]

Ok Stephen, update Pylons svn, and the pudge docs should build now.
The last tweaks needed were applied a little earlier today.

Cheers,
Ben

[James Gardner]

Hi,

You'll need Kid==0.9.3 (0.9.4 doesn't work) and you'll need to remove
all the .pyc files in docs/pudge_template too.

Once I've done this the main docs compile nicely, thanks Ben. I get the
following warning though:

C:\Documents and
Settings\James\Desktop\SVN\pylonshq.com\Pylons\trunk\docs\pudge
_template\common.py:326: SyntaxWarning: name 'top_level_module' is
assigned to before global declaration

This prevents any of the module docs compiling.

Any ideas how to tweak common.html so that top_level_module is defined
Ben? Does this not happen for you? Which version of Kid to you have?

Cheers,

James

[Stephen F. Steiner]

On Dec 20, 2006, at 3:55 PM, James Gardner wrote:
>
> Once I've done this the main docs compile nicely, thanks Ben. I get
> the following warning though:
>
> C:\Documents and Settings\James\Desktop\SVN\pylonshq.com\Pylons
> \trunk\docs\pudge
> _template\common.py:326: SyntaxWarning: name 'top_level_module' is
> assigned to before global declaration

I get that, then:

File "/Library/Frameworks/Python.framework/Versions/2.5/lib/python2.5/
site-packages/pudge-0.1.1dev_r130-py2.5.egg/pudge/browser.py", line
441, in _fill_modules_and_packages
module = safeimport('%s.%s' % (qname, modname))
File "/Library/Frameworks/Python.framework/Versions/2.5/lib/
python2.5/pydoc.py", line 305, in safeimport
raise ErrorDuringImport(path, sys.exc_info())
pydoc.ErrorDuringImport: problem in formencode.formgen - <class
'pkg_resources.DistributionNotFound'>: RuleDispatch

[Ben Bangert]

On Dec 20, 2006, at 12:55 PM, James Gardner wrote:

> You'll need Kid==0.9.3 (0.9.4 doesn't work) and you'll need to
> remove all the .pyc files in docs/pudge_template too.
>
> Once I've done this the main docs compile nicely, thanks Ben. I get
> the following warning though:
>
> C:\Documents and Settings\James\Desktop\SVN\pylonshq.com\Pylons
> \trunk\docs\pudge
> _template\common.py:326: SyntaxWarning: name 'top_level_module' is
> assigned to before global declaration
>
> This prevents any of the module docs compiling.
>
> Any ideas how to tweak common.html so that top_level_module is
> defined Ben? Does this not happen for you? Which version of Kid to
> you have?

I'm using 0.9.1, which was working ok, but now seems to be having
issues. I'd prefer to get 0.9.4 working since its the latest, though
at this point, the whole setup is annoying me so I'm looking at how
to have it use TG plugins so I can write the templates in something I
actually know... like Myghty. :)

If you have any idea how to fix the Kid templates, that'd be great...

Cheers,
Ben

[ssteiner]

Stephen F. Steiner wrote:
>
> I get that, then:
>
> File "/Library/Frameworks/Python.framework/Versions/2.5/lib/python2.5/
> site-packages/pudge-0.1.1dev_r130-py2.5.egg/pudge/browser.py", line
> 441, in _fill_modules_and_packages
> module = safeimport('%s.%s' % (qname, modname))
> File "/Library/Frameworks/Python.framework/Versions/2.5/lib/
> python2.5/pydoc.py", line 305, in safeimport
> raise ErrorDuringImport(path, sys.exc_info())
> pydoc.ErrorDuringImport: problem in formencode.formgen - <class
> 'pkg_resources.DistributionNotFound'>: RuleDispatch

This particular error was solved by:

sudo python ez_setup.py -Zf http://peak.telecommunity.com/snapshots/
RuleDispatch

As found at:

http://peak.telecommunity.com/

I didn't ever explicitly install RuleDispatch and it seems that
formencode requires it which gave safe_import() fits since it actually
wasn't there!

One down!

S

[ssteiner]

Now that I'm over the RuleDispatch hump, here's the next blocker:

Ju2:~/work/Pylons ssteiner$ python setup.py pudge
running pudge
generating documentation
/Library/Frameworks/Python.framework/Versions/2.5/lib/python2.5/site-packages/simplejson-1.4-py2.5.egg/simplejson/scanner.py:6:
DeprecationWarning: The sre module is deprecated, please import re.
from sre import VERBOSE, MULTILINE, DOTALL
error:
/Library/Frameworks/Python.framework/Versions/2.5/lib/python2.5/site-packages/Routes-1.6-py2.5.egg/routes:
Not a directory

Investigating...

S

[ssteiner]

This appears to be a Python 2.5 vs. setuptools issue.

Several eggs in my site-packages directory are not actually directories
themselves.

Examples from my site-packages from my 2.5 Python on OS X:

drwxr-xr-x 4 root admin 136 Dec 6 21:19
Myghty-1.1-py2.5.egg
-rw-r--r-- 1 root admin 48332 Dec 6 21:20
MyghtyUtils-0.52-py2.5.egg

...

-rw-r--r-- 1 root admin 37055 Dec 20 21:33
Routes-1.6-py2.5.egg
drwxr-xr-x 4 ssteiner admin 136 Dec 20 21:21
RuleDispatch-0.5a0.dev_r2100-py2.5-macosx-10.3-fat.egg
-rw-r--r-- 1 root admin 493362 Dec 14 20:07
SQLAlchemy-0.3.2-py2.5.egg
drwxr-xr-x 4 root admin 136 Dec 6 21:19
WebHelpers-0.2.2-py2.5.egg
...

So, I'm guessing that Python 2.5 + setuptools is creating bogus
installs for some packages and that's why I'm getting some of these
more bizarre errors.

Anyone have any thoughts on this?

Thanks,

S

[ssteiner]

ssteiner wrote:
> This appears to be a Python 2.5 vs. setuptools issue.
>
> Several eggs in my site-packages directory are not actually directories
> themselves.

Turns out that Routes 1.6 is not zip_safe under Python 2.5 (at least
with my setup).

Setting:

zip_safe=False

in setup.py and reinstalling did the trick.

S

[ssteiner]

Well...kind of did the trick.

Now I can run:

python setup.py pudge

but I get a ton of warnings and errors.

A bunch of:

'webhelpers.markdown hides module with same name'

Another bunch of:

webhelpers.textile.Textiler.table:10: (ERROR/3) Undefined substitution
referenced: "a|b|c".

with various "Undefined substituition..."s.

Also, since I've never actually been able to build the documentation
I'm not sure what it's supposed to look like but it doesn't appear to
have been styled at all -- no CSS, no nuthin'. All very straight,
plain, unadorned HTML with no included CSS or anything else.

The code seems to have been intended to be styled as there are class
references in the HTML that, presumably, would do something if the CSS
was properly included.

Starting index.html in the docs/html/docs/0.9.3 gives the basic front
page and all the links work except that the link to WebHelpers Module
Reference is broken.

There are a ton of other html files spewed into the same directory but
none are linked to by the main index.html. These all can be opened and
render without decoration of any form.

I'm not sure what this is all supposed to look like but I doubt this is
it...

Thanks,

S

[Ben Bangert]

On Dec 21, 2006, at 11:12 AM, ssteiner wrote:

> but I get a ton of warnings and errors.
>
> A bunch of:
>
> 'webhelpers.markdown hides module with same name'

Yep, that's normal.

> Another bunch of:
>
> webhelpers.textile.Textiler.table:10: (ERROR/3) Undefined substitution
> referenced: "a|b|c".

That's normal as well. :)

> with various "Undefined substituition..."s.
>
> Also, since I've never actually been able to build the documentation
> I'm not sure what it's supposed to look like but it doesn't appear to
> have been styled at all -- no CSS, no nuthin'. All very straight,
> plain, unadorned HTML with no included CSS or anything else.

Right, when we build the docs and push them to the server, the server
dynamically skins them for the PylonsHQ site. I'll have to add
another pudge template for offline building so that they can have a
full layout when not being built for the PHQ site.

> The code seems to have been intended to be styled as there are class
> references in the HTML that, presumably, would do something if the CSS
> was properly included.

You can run a local copy of the PylonsHQ site, but I'd imagine a
plain HTML version would be the desired format.

> Starting index.html in the docs/html/docs/0.9.3 gives the basic front
> page and all the links work except that the link to WebHelpers Module
> Reference is broken.
>
> There are a ton of other html files spewed into the same directory but
> none are linked to by the main index.html. These all can be opened
> and
> render without decoration of any form.
>
> I'm not sure what this is all supposed to look like but I doubt
> this is
> it...

It is for the most part actually, since the site is doing the
skinning. It's taking advantage of a Myghty ability called automatic
inheritance so that all the files will properly pull in the skin.
There's files that are referenced by the module docs, and the main
directory that is referenced by index. As you noticed, there's also
some docs that are in Pylons docs/ tree that are not linked to from
index, these are generally 'under development' and not ready for
prime-time. They probably need to be cleaned out if they're no longer
being worked on, thanks for noticing that. :)

I'll ping the other devs to ask if they have any 'dead' docs in there
that should be removed.

Cheers,
Ben

[Stephen F. Steiner]

>> Also, since I've never actually been able to build the documentation
>> I'm not sure what it's supposed to look like but it doesn't appear to
>> have been styled at all -- no CSS, no nuthin'. All very straight,
>> plain, unadorned HTML with no included CSS or anything else.
>
> Right, when we build the docs and push them to the server, the
> server dynamically skins them for the PylonsHQ site. I'll have to
> add another pudge template for offline building so that they can
> have a full layout when not being built for the PHQ site.

Got it, that makes sense.

>> I'm not sure what this is all supposed to look like but I doubt
>> this is
>> it...
>
> It is for the most part actually, since the site is doing the
> skinning. It's taking advantage of a Myghty ability called
> automatic inheritance so that all the files will properly pull in
> the skin. There's files that are referenced by the module docs,
> and the main directory that is referenced by index. As you
> noticed, there's also some docs that are in Pylons docs/ tree that
> are not linked to from index, these are generally 'under
> development' and not ready for prime-time. They probably need to
> be cleaned out if they're no longer being worked on, thanks for
> noticing that. :)
>
> I'll ping the other devs to ask if they have any 'dead' docs in
> there that should be removed.

Cool.

Can you confirm that Routes 1.6 isn't zip_safe on Python 2.5?

Thanks,