473,327 Members | 2,103 Online
Bytes | Software Development & Data Engineering Community
Post Job

Home Posts Topics Members FAQ

Join Bytes to post your question to a community of 473,327 software developers and data experts.

What documentation "standard" to use

I'm confused of how I should document my code, I've always liked being able
to document my code directly in my source file and then to use some tool to
extract the documentation to some other format.

My problem with Python is that there are so many tools and formats ... I
don't know which one I should use. I've tried to figure out if there is one
that is the "de-facto standard" but ...

Could someone advice me on what format/tool I should use?

Oct 5 '05 #1
2 1720
On Oct 05, Kalle Anke wrote:
I'm confused of how I should document my code, I've always liked being
able to document my code directly in my source file and then to use
some tool to extract the documentation to some other format. My problem with Python is that there are so many tools and formats ...
I don't know which one I should use. I've tried to figure out if there
is one that is the "de-facto standard" but ...


You don't need to do any marking up to use pydoc -- just put your
comments in the right place so that they become docstrings. Just try
"pydoc pydoc" for more info. It is distributed with Python, and
generates nicely colored html or opens your PAGER.

Or you could install epydoc <http://epydoc.sourceforge.net/>, which has
similar features (and more). It supports "reStructuredText"
<http://docutils.sourceforge.net/rst.html> and it's own markup (epytext,
I think). RST is the de-facto Python markup, AFAICT. You'll need
something like "__docformat__ = 'restructuredtext'" in your modules.
RST is great for non-Python-source code, too.

Those are the two I am aware of.

--
Micah Elliott
<md*@micah.elliott.name>
Oct 5 '05 #2
This is, as far as I'm concerned, one of the great weaknesses of
Python. (One of a
relatively few, to be honest--I'm still an enthusiast after all!)

There are numerous docstring-oriented tools; in my opinion, none of
them are satisfactory,
because docstrings only apply to certain entities, and there are many
other entities one
might wish to document.

Fred Lundh pointed out just a day or two ago a program of his called
PythonDoc where
documentation is put into comments, and from the brief look I had at
it, I may start
using it, it looks pretty nice.

ReStructuredText (now called ReST, I believe) looks like it's finally
become a quite
good text markup language, and if there were a non-docstring system
that used it, I
think that also would be good.

But what I'd really like is for Guido et al to declare a standard
documentation system and
include in the standard Python distro. That way we would have _some_
standard, and
people could concentrate their energy on improving it, rather than on
continually
coming up with their own, non-interoperable, solutions.

Cheers,
Ken

On 5-Oct-05, at 3:26 PM, Kalle Anke wrote:
I'm confused of how I should document my code, I've always liked
being able
to document my code directly in my source file and then to use some
tool to
extract the documentation to some other format.

My problem with Python is that there are so many tools and
formats ... I
don't know which one I should use. I've tried to figure out if
there is one
that is the "de-facto standard" but ...

Could someone advice me on what format/tool I should use?

--
http://mail.python.org/mailman/listinfo/python-list


Oct 6 '05 #3

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

Similar topics

38
by: Jack Klein | last post by:
Many people, including me, like having hard copy books at hand, along with electronic editions. When I first heard of this book several months ago, I pre-ordered a copy. It arrived from...
4
by: Luke Wu | last post by:
I am just wondering what the following terms usually mean: 1) "Standard C" 2) "K&R C" 3) "ANSI C" I am pretty sure "ANSI C" usually refers to the C89 standard, but what
5
by: VB Programmer | last post by:
If you want to store custom tables in ASP.NET 2.0, such as Products, Companies, Shopping Carts, etc... where is the standard place to put the tables? I want to link it to the user/membership...
5
by: funkyj | last post by:
I love pexpect because it means I may never have to use expect again (I don't do any heavy expect lifting -- I just need simple tty control)! As a python advocate I find it embarassing how...
6
by: Steph. | last post by:
Hi ! How can I play "standard system sounds" in C# ? ( "standard system sounds" = The kind of sound you hear when you use MessageBox.Show() ) Thanks ! steph.
3
by: sbaird | last post by:
Aloha from Hawaii, I'm beating my head on the wall here. I have a recruiting contact managment database I'm trying to create. Managers (there ar 14 of them) have to make a certain number of...
2
by: Royt | last post by:
Have a look at this site: http://blogs.msdn.com/vcblog/archive/2007/11/05/iso-c-standard-update.aspx C is a mature language used everywhere, it doesn't belong to any commercial company, should...
0
by: ryjfgjl | last post by:
ExcelToDatabase: batch import excel into database automatically...
0
by: Vimpel783 | last post by:
Hello! Guys, I found this code on the Internet, but I need to modify it a little. It works well, the problem is this: Data is sent from only one cell, in this case B5, but it is necessary that data...
0
by: jfyes | last post by:
As a hardware engineer, after seeing that CEIWEI recently released a new tool for Modbus RTU Over TCP/UDP filtering and monitoring, I actively went to its official website to take a look. It turned...
0
by: ArrayDB | last post by:
The error message I've encountered is; ERROR:root:Error generating model response: exception: access violation writing 0x0000000000005140, which seems to be indicative of an access violation...
1
by: Defcon1945 | last post by:
I'm trying to learn Python using Pycharm but import shutil doesn't work
1
by: Shællîpôpï 09 | last post by:
If u are using a keypad phone, how do u turn on JavaScript, to access features like WhatsApp, Facebook, Instagram....
0
by: af34tf | last post by:
Hi Guys, I have a domain whose name is BytesLimited.com, and I want to sell it. Does anyone know about platforms that allow me to list my domain in auction for free. Thank you
0
by: Faith0G | last post by:
I am starting a new it consulting business and it's been a while since I setup a new website. Is wordpress still the best web based software for hosting a 5 page website? The webpages will be...
0
isladogs
by: isladogs | last post by:
The next Access Europe User Group meeting will be on Wednesday 3 Apr 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 former...

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.