Bob Ippolito wrote:
I managed to get pudge to build the documentation for simplejson:
http://svn.red-bean.com/bob/simplejson/trunk/docs/index.html
I had to make several patches in order to make it work like that:
Trivial patch to fill in some defaults to make all of the built-in
templates build without specifying license or organization_url:
http://lesscode.org/projects/pudge/ticket/7
Applied.
Probably mostly broken patch to get the source code to build for
modules that don't show up in __all__ (so the JSONEncoder and
JSONDecoder source links work):
http://lesscode.org/projects/pudge/ticket/8
The patch seems fine. At least it's easy to understand ;) I want to
look through how the finding works, as I think there needs to some more
ways to indicate things:
* Some modules should not be listed. I have backported stdlib modules
for instance, and I don't want these to show up in the documentation.
* Some modules should not show up in the module index. Deprecated
modules, for instance.
* Some modules appear to belong to the package, but don't really. I'm
having this problem with namespace packages in paste (multiple projects
use the paste package).
* Some objects should not be displayed in the module index. This
includes deprecated objects, and private objects.
* Some private objects should still have their docstrings rendered,
because there interface is public in some way. For instance, when a
function returns an instance of some class -- the class itself may be
private, but the interface of the class is public. I think this should
be handled by putting in a link in the function docstring to the class,
but the class itself shouldn't be in the index.
* Some objects are fully public, but don't show up in __all__. I added
a __pudge_all__ variable that overrides __all__ just for the purposes of
pudge for this.
So I think some distinction more than just isvisible is called for.
Relatively big patch to use "unobtrusive javascript" techniques to make
the docs work without a webserver by stowing away the line range inside
of a class name rather than directly on the query string:
http://lesscode.org/projects/pudge/ticket/9
Is this a Safari issue or somesuch? Firefox works fine for me in local
browsing.
I think this patch is against an older version; I updated the Javascript
recently to do better highlighting. But I haven't actually tried
applying it. Ryan can give you commit access too if you want it.
I'm also just copying over one of the files on top of index.html with
this script, because the module index is all I really needed:
http://svn.red-bean.com/bob/simplejson/trunk/scripts/make_docs.py
I find the index handling funny in pudge; I think index files could be
treated just like normal files, and then this shouldn't be a problem.
In the future, it would be nice if more license templates were in
there. Personally I'd like to use either a public domain or CC
attribution license. No patch on this one:
http://lesscode.org/projects/pudge/ticket/6
Do we need to include the text of the license on the site itself? Is a
link to the original license sufficient? If so, I'd like to make the
license field at least optionally a link.
--
Ian Bicking | [EMAIL PROTECTED] | http://blog.ianbicking.org
_______________________________________________
Pudge mailing list
[email protected]
http://lesscode.org/mailman/listinfo/pudge
