What's "the standard" for code docs?

[Preston Landers]

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

 

[Torsten Bronger]

Hallöchen!

[...]

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.

 

[Jeff Schwab]

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]

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]

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

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

 

[castironpi]

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

man serious

 

[Preston Landers]

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.

 

[castironpi]

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]

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

As opposed to woman serious?

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

-tkc

 

[Preston Landers]

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]

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

 

[cokofreedom]

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

Diez

Doxygen is your friend!

 

[Paul McGuire]

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

I use epydoc for pyparsing, and I really like the results. Just make
sure that importing your modules doesn't really do anything
substantial (like connect to db's, or run unit tests that run for
hours); epydoc imports your code and then introspects it to extract
the classes, methods, docstrings, etc.

(And I think you asked an honest question, and did not deserve the
rude answers you got. This NG is normally better behaved.)

-- Paul

 

[Marc 'BlackJack' Rintsch]

On Feb 19, 4:31 pm, (e-mail address removed) wrote:

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.

Have a little bit patience, the bot is still in its early learning phase. ;-)

Ciao,
Marc 'BlackJack' Rintsch

 

[Paul Boddie]

I use epydoc for pyparsing, and I really like the results. Just make
sure that importing your modules doesn't really do anything
substantial (like connect to db's, or run unit tests that run for
hours); epydoc imports your code and then introspects it to extract
the classes, methods, docstrings, etc.

Or use the --parse-only option to avoid the introspection.

(And I think you asked an honest question, and did not deserve the
rude answers you got. This NG is normally better behaved.)

Indeed.

Paul

 

[Preston Landers]

I use epydoc for pyparsing, and I really like the results. Just make
sure that importing your modules doesn't really do anything
substantial (like connect to db's, or run unit tests that run for
hours); epydoc imports your code and then introspects it to extract
the classes, methods, docstrings, etc.

OK thanks for the advice. We already have a policy of not doing
anything "heavyweight" on module import so in introspection wouldn't
be a problem.

(And I think you asked an honest question, and did not deserve the
rude answers you got. This NG is normally better behaved.)

Yeah I've been lurking a long time. I've noticed a strange uptick in
weirdness lately. No clue why though.

 

[castironpi]

Have a little bit patience, the bot is still in its early learning phase.  ;-)

Ciao,
        Marc 'BlackJack' Rintsch

Everything! Nobody cares.
(setting person.care= 0.0 for person in people)
Processing...
That's not too bad actually.
Where's the bar?