473,581 Members | 2,239 Online
Bytes | Software Development & Data Engineering Community
+ Post

Home Posts Topics Members FAQ

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

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. Well, actually, there are some. For example,
the "PickAxe" book (google it), and "Why's" Poignant Guide.
But there's a disturbing lack of *built-in* docs for Ruby.
Now, the situation is getting better. In fact, it's getting
better very quickly. Let me explain.

IMO, Perl has docs nailed. I learned Perl before coming
to Python, and I can tell you that their docs kick butt.
I believe the reason why is (besides Larry's excellent
and entertaining writing) because of perldoc. Here's how
it works: they write special doc directives into their .pl
files that the interpreter ignores, but that the perldoc
command processes into a manpage for you. This is a *bit*
like what pydoc does, only pydoc just regurgitates docstrings,
while perldoc formats special directives into headings, code
listings, bulleted lists, etc.

Now, the *real* magic of perldoc is that it makes writing
small self-contained little manpage style docs easy as pie.
What this means is that really good doc writers can sit down
and quickly produce something that can be readily incorporated
into the perl-doc distribution. *That's* the magic. That's
why I think they've organically grown such an amazing crop
of great docs. Anyone can quickly and easily write docs that
the community can then filter to find the best ones.

Back to Ruby's docs. Their situation is getting better. This
is because they're picking up on Perl's doc success and doing
the same sort of thing. Only, I think their solution may be
clunkier because it requires a separate program (rdoc) to
process the doc directives, and then you actually read the
docs with a program called ri (not sure). Regardless of the
minute details, it looks like their docs are starting to get
better, rapidly.

Here's what I think is currently happening with Python
(please correct me if I'm wrong): There's the docutils project
http://docutils.sourceforge.net/ which, AFAICT, is working on a
number of complicated things, one of which is to have a way to
allow you to put reStructuredTex t markup (aka "reST")
( http://docutils.sourceforge.net/rst.html ) into your docstrings
(and presumably have the pydoc command understand it). There's
more info in PEP 287 http://www.python.org/doc/peps/pep-0287/ .

I certainly don't understand all that Docutils is trying to
do. All I'm convinced of is, the real magic is in being able to
quickly write a .py file containing marked up docstrings and
have the pydoc command be able to render it as something that
looks like a man page in my terminal window. If it can later
also produce html, that's great too. But *that's* the essense,
IMO, of what will foster community involvement in making the
docs great, as well as allowing folks to more easily document
their own modules and contribute integrated docs to all the
great modules already available.

It looks like we have the tools do this *right now*. We've got
the markup (reST), we've got the tools to churn that into a
manpage or html (part of docutils?), and we've got the pydoc
command. I think the current hangup is that the docutils guys
(being smart and ambitious folks) want to get some sort of
inter-doc linking thing working so you can refer from one doc
page to another (?). I don't think perldoc has (or needs) that
feature... maybe we could put that on the "would be nice to
have down the road" list, and get a quick common-sense
docstring-reST pydoc setup working for us much sooner? I
don't know for sure, but my guess is "yes".

Eventually, maybe the tutorial, language reference, library ref,
etc., could even all make it into this format, with the html
versions generated from the .py/docstring/reST sources. That might
make it easier for the community to contribute to them (if their
respective maintainers are interested in that).

Please note, I certainly don't want to step on the doc-sig folks'
toes here -- but rather to generate more interest in what they're
doing, and to help make Python be even better in an area that I
see it struggling.

What do you folks think?

Yes, I'm trying to make time to look at the docutils code and the
pydoc command to see what's involved. Unfortunately, my spare
time is vanishingly close to zero right now.

Related link:
Doc-SIG http://www.python.org/community/sigs/current/doc-sig/

Thanks,
---John

Mar 14 '06 #1
28 2977
> Please note, I certainly don't want to step on the doc-sig folks'
toes here -- but rather to generate more interest in what they're
doing, and to help make Python be even better in an area that I
see it struggling.

What do you folks think?

Yes, I'm trying to make time to look at the docutils code and the
pydoc command to see what's involved. Unfortunately, my spare
time is vanishingly close to zero right now.

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.

Diez
Mar 14 '06 #2
Thanks Diez! Epydoc looks great.

Can we use epytext to generate output suitable for a manpage?

Do you prefer epytext or reST?

Mar 14 '06 #3
> Thanks Diez! Epydoc looks great.

Can we use epytext to generate output suitable for a manpage?
Don't know, never tried that.
Do you prefer epytext or reST?


So far epytext suited my needs.

Diez
Mar 14 '06 #4
> So far epytext suited my needs.

I like it too.

Ok, now I'm starting to get excited. :)

Mar 14 '06 #5
Diez B. Roggisch wrote:
Thanks Diez! Epydoc looks great.

Can we use epytext to generate output suitable for a manpage?

Don't know, never tried that.

The answer appear to be No, but there is a man.py file which indicates
that some work was done on it.

Below is the epydoc commandline guide.

Colin W.

epydoc [OPTIONS] MODULES...

MODULES... The Python modules to document.
--html Generate HTML output (default).
--latex Generate LaTeX output.
--pdf Generate pdf output, via LaTeX.
--check Run documentation completeness checks.
-o DIR, --output DIR The output directory.
-n NAME, --name NAME The documented project's name.
-u URL, --url URL The documented project's url.
-t PAGE, --top PAGE The top page for the HTML documentation.
-c SHEET, --css SHEET CSS stylesheet for HTML files.
--private-css SHEET CSS stylesheet for private objects.
--inheritance STYLE The format for showing inherited objects.
-V, --version Print the version of epydoc.
-h, -?, --help, --usage Display this usage message.
-h TOPIC, --help TOPIC Display information about TOPIC (docformat,
css, inheritance, usage, or version).
Do you prefer epytext or reST?

So far epytext suited my needs.

Diez

Mar 14 '06 #6
Ok. I'm going to try and make something happen. Give me a day or so.

:)
---John

Mar 14 '06 #7
jo***********@y ahoo.com <jo***********@ yahoo.com> wrote:
IMO, Perl has docs nailed. I learned Perl before coming
to Python, and I can tell you that their docs kick butt.
I believe the reason why is (besides Larry's excellent
and entertaining writing) because of perldoc. Here's how
it works: they write special doc directives into their .pl
files that the interpreter ignores, but that the perldoc
command processes into a manpage for you. This is a *bit*
like what pydoc does, only pydoc just regurgitates docstrings,
while perldoc formats special directives into headings, code
listings, bulleted lists, etc.


As another perl refugee I agree with you 100% here.

"perldoc perltoc" then "perldoc xxxx" will find you anything in perl.

Its frustrating that pydoc is only half (or less) of the docs.

However having bedded into python for a few years, I now just reach
for my web browser for the global module index instead of pydoc. Its
not as good as perldoc as it doesn't cover all the modules I've got
installed, but its very good documentation. Some modules have good
pydoc-umentation but not all of them. Code examples tend to be
missing.

I think a major problem with our way of thinking about
perldoc/pydoc/man pages is that it is a) unix centric, and b) possibly
a bit old fashioned! a) and b) apply to perl certainly, but I don't
think they apply to python in the same way.

I'd love to have a unified documentation system where *all* the
documentation for *all* installed modules was available to pydoc *and*
the web browser and *all* this documentation was in .py files.

(Putting the code together with the documentation is essential in my
opinion and experience - if you seperate the two then the documention
will lag the code.)

PS I've used reST and perldoc. reST is easier to use for the easy
things, but gets complicated for the hard things.

--
Nick Craig-Wood <ni**@craig-wood.com> -- http://www.craig-wood.com/nick
Mar 14 '06 #8
On 14 Mar 2006 09:25:07 -0800
jo***********@y ahoo.com wrote:
Do you prefer epytext or reST?


I personally prefer epytext primarily because it has support
for greek letters and math symbols. That could be very
useful in documenting certain kinds of software. OTOH, I
haven't had much occasion to use that feature (once upon a
time almost all the software I wrote was scientific, but it
seems I've pretty much given it up -- not that I
particularly planned to, but it's turned out that way).

I was under the impression that pydoc already interpreted
restructured text notation, but maybe I was wrong. I don't
like pydoc because it doesn't make useable static
documentation sets -- that's where epydoc (which I suppose
stands for "extended pydoc") shines.

Although it's great to have "manpage" type help, I
personally find HTML documentation much easier to read and
browse. Pydoc can do this if you are willing to use it as a
server, but it doesn't do so well at making an in-package
website, which is what I usually want to do.

There's also happydoc, which was better than either at
discovering documentation, but stagnated somewhere between
2.x and 3.x with bugs that make it fairly unusable. What
would be cool is if some of happydoc's unique features were
ported to epydoc (such as getting information from comments
as well as docstrings).

--
Terry Hancock (ha*****@Anansi Spaceworks.com)
Anansi Spaceworks http://www.AnansiSpaceworks.com

Mar 14 '06 #9
I agree that more progress is needed on the Python documentation
front. For example if you look at the "codecs" module documentation
there is no hint of what a codec is anywhere that I can see. Also
the distinction between an "encoder" and a "decoder" is not explained.
Even though I've used it many times and understand it, I still find
myself using the interactive interpreter to make sure I'm sending the
bytes in the right direction...

Perhaps some faqwiz/wiki-like tool to allow the broader community to
propose documentation enhancements would be useful?

-- Aaron Watters

===

"I know what it's like to put food on my family." G.W.Bush

Mar 14 '06 #10

This thread has been closed and replies have been disabled. Please start a new discussion.

Similar topics

220
18931
by: Brandon J. Van Every | last post by:
What's better about Ruby than Python? I'm sure there's something. What is it? This is not a troll. I'm language shopping and I want people's answers. I don't know beans about Ruby or have any preconceived ideas about it. I have noticed, however, that every programmer I talk to who's aware of Python is also talking about Ruby. So it...
54
6535
by: Brandon J. Van Every | last post by:
I'm realizing I didn't frame my question well. What's ***TOTALLY COMPELLING*** about Ruby over Python? What makes you jump up in your chair and scream "Wow! Ruby has *that*? That is SO FRICKIN' COOL!!! ***MAN*** that would save me a buttload of work and make my life sooooo much easier!" As opposed to minor differences of this feature...
0
8144
Oralloy
by: Oralloy | last post by:
Hello folks, I am unable to find appropriate documentation on the type promotion of bit-fields when using the generalised comparison operator "<=>". The problem is that using the GNU compilers, it seems that the internal comparison operator "<=>" tries to promote arguments from unsigned to signed. This is as boiled down as I can make it. ...
0
8301
jinu1996
by: jinu1996 | last post by:
In today's digital age, having a compelling online presence is paramount for businesses aiming to thrive in a competitive landscape. At the heart of this digital strategy lies an intricately woven tapestry of website design and digital marketing. It's not merely about having a website; it's about crafting an immersive digital experience that...
1
7894
by: Hystou | last post by:
Overview: Windows 11 and 10 have less user interface control over operating system update behaviour than previous versions of Windows. In Windows 11 and 10, there is no way to turn off the Windows Update option using the Control Panel or Settings app; it automatically checks for updates and installs any it finds, whether you like it or not. For...
1
5670
isladogs
by: isladogs | last post by:
The next Access Europe User Group meeting will be on Wednesday 1 May 2024 starting at 18:00 UK time (6PM UTC+1) and finishing by 19:30 (7.30PM). In this session, we are pleased to welcome a new presenter, Adolph Dupré who will be discussing some powerful techniques for using class modules. He will explain when you may want to use classes...
0
5361
by: conductexam | last post by:
I have .net C# application in which I am extracting data from word file and save it in database particularly. To store word all data as it is I am converting the whole word file firstly in HTML and then checking html paragraph one by one. At the time of converting from word file to html my equations which are in the word document file was convert...
0
3820
by: adsilva | last post by:
A Windows Forms form does not have the event Unload, like VB6. What one acts like?
1
2300
by: 6302768590 | last post by:
Hai team i want code for transfer the data from one system to another through IP address by using C# our system has to for every 5mins then we have to update the data what the data is updated we have to send another system
1
1400
muto222
by: muto222 | last post by:
How can i add a mobile payment intergratation into php mysql website.
0
1132
bsmnconsultancy
by: bsmnconsultancy | last post by:
In today's digital era, a well-designed website is crucial for businesses looking to succeed. Whether you're a small business owner or a large corporation in Toronto, having a strong online presence can significantly impact your brand's success. BSMN Consultancy, a leader in Website Development in Toronto offers valuable insights into creating...

By using Bytes.com and it's services, you agree to our Privacy Policy and Terms of Use.

To disable or enable advertisements and analytics tracking please visit the manage ads & tracking page.