Joe Gregorio
Pudge is a documentation system for Python that generates documentation files from docstrings and uses Restructured Text syntax. You can see a running example in Python Paste. Maybe you could give it a try.
Pudge does look promising. I was able to successfully pull the code from subversion, and after a small patch ;) to setup.py, I was able to install it:
Index: setup.py
===================================================================
--- setup.py (revision 134)
+++ setup.py (working copy)
@@ -1,6 +1,5 @@
# bootstrap setuptools if necessary
-from ez_setup import use_setuptools
-use_setuptools()
+from distutils.core import setup
import os
import os.path
@@ -38,7 +37,6 @@
('licenses', )]:
package_data.extend(get_data_files(os.path.join(*subdir)))
-from setuptools import setup
setup(
name=name,
I wanted to check the archives to see if there had been a discussion about the use of setuptools, but it appears the mailing list, linked from the front page of the project, has gone 404.
Posted by Jonathan LaCour on 2007-03-23
Posted by Eivind Uggedal on 2007-03-23
I think this aspect is really hurting python takeoff among new comers as much as it's bothering seasoned python programmers dealing.
Unfortunately the python core developers are underestimating this problem, python badly needs *one and only one* documentation tool, and while I think we can live with so many web framework I think a documentation tool it's so *crucial* that there should be *one and only one*, working well and easily.
Regarding Pudge, I will quote Jonathan, it's pretty nice, it produces good looking and usable output (just look at Elixir docs), it's not trying to mimic javadoc (like epydoc) since you can't document python in the same way you document java (where everything is always inside a class), it has nice syntax coloring of source code that you can navigate, it uses a lightweight markup like Rest instead of an heavy one like javadoc.
Unfortunately, as Jonathan said, Ryan (the original author) has left python development for Ruby and RoR but luckily before doing so he also left us with Kid and Pudge, two brilliant ideas but almost unmaintained.
Thanks to Genshi we've got what Ryan envisioned as Kid 2.0 [2] and it is in a pretty good state [3].
Someone should do the same by picking up the poor Pudge, porting it to Kid 2.0 (==Genshi) as Jonathan said, giving it a new home (webfaction offers free trac hosting for python opensource projects), new features and giving python a rocking documentation tool.
I can't do it right now, but I *may* end-up doing it (after summer 2007) if someone doesn't. ;-)
[1] http://bitworking.org/news/148/Five-things-I-hate-about-Python
[2] http://tomayko.com/articles/2006/11/11/xml-templating-in-python-evolves
[3] http://genshi.edgewall.org/timeline
Posted by michele on 2007-03-23
Yeah, a few of us maintain Pudge enough to keep it alive. But barely. Together with buildutils it makes it fairly easy to maintain a small project.
I agree we really need a real documentation system, though I think it doesn't need to be a completely singular system. There's at least three distinct pieces, I think: displaying source, extracted reference documentation, and hand-written documentation. And probably other pieces, like wikis and whatnot. Once you have a set of these tools working together, allowing any one of these tools to be implemented by more than one package isn't that big a deal.
I still think the decomposition of the problem I outlined on my blog would be a good way to approach it, and allows for the adaptation of existing documentation (e.g., epydoc) projects and achieving useful intermediate results.
Posted by Ian Bicking on 2007-03-23
Posted by Ryan Tomayko on 2007-03-24
Posted by Jeff on 2007-03-23