[lnkForumImage]
TotalShareware - Download Free Software
Confronta i prezzi di migliaia di prodotti.
Asp Forum
 Home | Login | Register | Search 


 

Forums >

comp.lang.python

What's "the standard" for code docs?

Preston Landers

2/15/2008 5:00:00 PM

Hey guys and gals. What are all the cool kids using these days to
document their code? My goal is to create in-line documentation of
each package/module/class/method and create some semi-nice looking (or
at least usable) packaged documentation from it, in HTML and/or PDF
format.

I've been using effbot's PythonDoc for a while, but it seems like "the
new standard" (if there is one) is docutils and restructured text
(ReST.) Is that accurate?

Just from glancing at some samples of ReST the actual format looks
much easier to work with in "plain text" in the text editor.
PythonDoc has not been very popular with my team due to its HTML-ish
nature and I think ReST will gain more acceptance. Of course I don't
want to bother making the jump from PythonDoc to docutils if that
project is somehow a dead end.

thanks for any info or advice you can provide.

Preston
16 Answers

Torsten Bronger

2/15/2008 5:11:00 PM

0

Hallöchen!

Preston Landers writes:

> [...]
>
> I've been using effbot's PythonDoc for a while, but it seems like
> "the new standard" (if there is one) is docutils and restructured
> text (ReST.) Is that accurate?

In my opinion this is true. And with Epydoc being the best tool for
generating documentation from the source code, Epydoc+reST is the
way to go.

Tschö,
Torsten.

--
Torsten Bronger, aquisgrana, europa vetus
Jabber ID: bronger@jabber.org
(See http://ime.... for further contact info.)

Jeff Schwab

2/15/2008 6:35:00 PM

0

Preston Landers wrote:
> Hey guys and gals. What are all the cool kids using these days to
> document their code? My goal is to create in-line documentation of
> each package/module/class/method and create some semi-nice looking (or
> at least usable) packaged documentation from it, in HTML and/or PDF
> format.
>
> I've been using effbot's PythonDoc for a while, but it seems like "the
> new standard" (if there is one) is docutils and restructured text
> (ReST.) Is that accurate?
>
> Just from glancing at some samples of ReST the actual format looks
> much easier to work with in "plain text" in the text editor.
> PythonDoc has not been very popular with my team due to its HTML-ish
> nature and I think ReST will gain more acceptance. Of course I don't
> want to bother making the jump from PythonDoc to docutils if that
> project is somehow a dead end.

Currently using doxygen.

John Nagle

2/16/2008 7:57:00 AM

0

Preston Landers wrote:
> Hey guys and gals. What are all the cool kids using these days to
> document their code?

HTML. Text-only docs are so last-cen.

John Nagle

Preston Landers

2/19/2008 10:13:00 PM

0

On Feb 16, 1:56 am, John Nagle <na...@animats.com> wrote:
> Preston Landers wrote:
> > Hey guys and gals. What are all the cool kids using these days to
> > document their code?
>
> HTML. Text-only docs are so last-cen.

My sarcasometer is broken today... are you being serious?

Aaron Brady

2/19/2008 10:17:00 PM

0

On Feb 19, 4:12 pm, Preston Landers <pland...@gmail.com> wrote:
> On Feb 16, 1:56 am, John Nagle <na...@animats.com> wrote:
>
> > Preston Landers wrote:
> > > Hey guys and gals.  What are all the cool kids using these days to
> > > document their code?
>
> >    HTML.  Text-only docs are so last-cen.
>
> My sarcasometer is broken today... are you being serious?

man serious

Preston Landers

2/19/2008 10:22:00 PM

0

On Feb 19, 4:16 pm, castiro...@gmail.com wrote:
> On Feb 19, 4:12 pm, Preston Landers <pland...@gmail.com> wrote:
>
> > On Feb 16, 1:56 am, John Nagle <na...@animats.com> wrote:
>
> > > Preston Landers wrote:
> > > > Hey guys and gals. What are all the cool kids using these days to
> > > > document their code?
>
> > > HTML. Text-only docs are so last-cen.
>
> > My sarcasometer is broken today... are you being serious?
>
> man serious

As opposed to woman serious?

Are people really writing pure HTML snippets in docstrings to document
each module/class/method? For anything other than a toy project?

One of the main reasons I'm considering moving to epydoc + reST is
precisely because it's very un-HTML.

Mind you I want to be able to produce HTML format docs from the
source, but I don't want to actually *put* HTML anywhere near my
precious sources.

Aaron Brady

2/19/2008 10:31:00 PM

0

On Feb 19, 4:21 pm, Preston Landers <pland...@gmail.com> wrote:
> On Feb 19, 4:16 pm, castiro...@gmail.com wrote:
>
> > On Feb 19, 4:12 pm, Preston  Landers <pland...@gmail.com> wrote:
>
> > > On Feb 16, 1:56 am, John Nagle <na...@animats.com> wrote:
>
> > > > Preston Landers wrote:
> > > > > Hey guys and gals.  What are all the cool kids using these days to
> > > > > document their code?
>
> > > >    HTML.  Text-only docs are so last-cen.
>
> > > My sarcasometer is broken today... are you being serious?
>
> > man serious
>
> As opposed to woman serious?
>
> Are people really writing pure HTML snippets in docstrings to document
> each module/class/method?  For anything other than a toy project?
>
> One of the main reasons I'm considering moving to epydoc + reST is
> precisely because it's very un-HTML.
>
> Mind you I want to be able to produce HTML format docs from the
> source, but I don't want to actually *put* HTML anywhere near my
> precious sources.

bash-2.04$ man precious

Tim Chase

2/19/2008 10:32:00 PM

0

>>>> HTML. Text-only docs are so last-cen.
>>> My sarcasometer is broken today... are you being serious?
>> man serious
>
> As opposed to woman serious?

tim@rubbish:~$ man -k serious
serious: nothing appropriate.

-tkc

Preston Landers

2/20/2008 12:37:00 AM

0

On Feb 19, 4:31 pm, castiro...@gmail.com wrote:

> bash-2.04$ man precious

I understand now that you were referring to unix manual pages, but I'm
afraid I still don't understand what your original reply (man serious)
has to do with anything in particular.

But after reading some of your other recent posts on other topics, I'm
not confident that it was intended to make sense at all.

Diez B. Roggisch

2/20/2008 8:13:00 AM

0


> Are people really writing pure HTML snippets in docstrings to document
> each module/class/method? For anything other than a toy project?
>
> One of the main reasons I'm considering moving to epydoc + reST is
> precisely because it's very un-HTML.
>
> Mind you I want to be able to produce HTML format docs from the
> source, but I don't want to actually *put* HTML anywhere near my
> precious sources.

In the Java-world it *is* pure HTML snipplets... but no, not in python.

Diez