Tried Ruby (or, "what Python *really* needs" or "perldoc!")

[Marc 'BlackJack' Rintsch]

You heard of epydoc? http://epydoc.sourceforge.net/

It pretty much does what you say I think - and for my personal projects I
use it. Maybe we an adopt it as standard-tool.

Epydoc seems to be "dead" and pudge not yet alive:

http://pudge.lesscode.org/

But it looks promising IMHO.

Ciao,
Marc 'BlackJack' Rintsch

 

[Nick Craig-Wood]

Why don't you instead install the info version of the Python
documentation on your server. Then you can do "info Python2.3-lib"
and have at it.

I didn't know about that. Its very good.

Its still not all the documentation for all the installed modules
(a-la perltoc) but it is much better than I thought!

info on its own reveals these possible info packages for python

Python
* Python2.3-api: (python2.3-api). Python/C 2.3 API Reference Manual
* Python2.3-dist: (python2.3-dist). Distributing Python Modules (2.3)
* Python2.3-ext: (python2.3-ext). Extending & Embedding Python 2.3
* Python2.3-lib: (python2.3-lib). Python 2.3 Library Reference
* Python2.3-ref: (python2.3-ref). Python 2.3 Reference Manual
* Python2.3-tut: (python2.3-tut). Python 2.3 Tutorial

 

[Terry Hancock]

Epydoc seems to be "dead" and pudge not yet alive:

What leads you to this conclusion? Works pretty well for
me. Maybe it's just "stable"?

 

[Steve Juranich]

This "release" is as alpha as alpha gets. It's so alpha it
actually loops back around to zeta -- but it's a start, and I
think it's exactly what the Python community needs.

Not to pick nits, but that should actually be "... so alpha that it actually
loops back around to *OMEGA*."

Cheers.

 

[john_sips_tea]

Why don't you instead install the info version of the Python
documentation on your server. Then you can do "info Python2.3-lib"
and have at it. If you are hacking in emacs then this is about as
slick a documentation system as you could ask for, but even if you use
some other editor info is a much better documentation tool than man.

You know, I'm pretty used to reading man pages. There's only a
few simple keystrokes I need to remember, and the only time I
ever touch "info" is when a very short man page tells me that the
real docs are in info and I need to look there. At that point, I have
to relearn how to use that info command. Info is complicated. It's
got some concept of nodes being hierarcical, but also they seem
to have some order to them (a la next and previous) as well. No
idea what the connection between those is. Also it's got "cross-
references" as well as menus -- dunno if they're different or not.
Bah. Why not just use html and browse it with lynx/links/links2/elinks?

I can't understand why we need two separate and distinct doc
formats: man and info. My take: write your docs in some markup
that can produce both man output and html. Done and done.
Seems like two good candidates for that are epytext and
reStructuredText ("reST").

Python does match (and exceed) Perl for docs available on the command
line. Once you get used to using the excellent info-based Python
documentation using man is downright primitive.

Jason

I think that may be wishful thinking. When I use the pydoc command,
I mostly get *very* short API docs with *no* example code or tutorial
notes at all.

Contrast that with perldoc which is categorized and complete docs
for the entire language plus tutorials, faqs, ports info, ... I mean,
have a look over at http://perldoc.perl.org/perl.html -- everything
there is at your fingertips from the terminal! And it's written by
folks
like Larry, Dominus, Randal Schwartz, Tom Christiansen, et al. I've
never come across a FLOSS software project with docs as good as
Perl's.

Now, the one big thing we have going for us is that since Python
is a simpler language, so it needs few docs overall anyway.

---John
http://www.simisen.com/jmg/cpd/

 

[Tim Roberts]

Just tried Ruby over the past two days. I won't bore you
with the reasons I didn't like it, however one thing really
struck me about it that I think we (the Python community)
can learn from.

Ruby has ... an issue with docs. That is to say, there are
almost none. ...

IMO, Perl has docs nailed.

I know there are people who disagree with me, but I think the PHP community
has the right idea with their online docs. The wiki-like community
participation adds a helpful extra dimension, giving practical tips and
pointing out non-obvious gotchas.

However, I'm sure it's a bear to administer.

 

[Joel Hedlund]

This "release" is as alpha as alpha gets. It's so alpha it

Not to pick nits, but that should actually be "... so alpha that it actually
loops back around to *OMEGA*."

I think he's using extended Greek++. That got seriously big around the late B.C's.

/Joel

Sorry for this garbage post, btw... Couldn't help myself...

 

[Marc 'BlackJack' Rintsch]

What leads you to this conclusion? Works pretty well for
me. Maybe it's just "stable"?

But Docutils is a moving target and now and then the combination of both
breaks and Epydoc doesn't get fixed officially. There are patches in the
Source Forge tracker I have to apply myself and it doesn't look like they
will be merged into a new Epydoc release.

Ciao,
Marc 'BlackJack' Rintsch