Re: What's the standard for code docs?
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 -- http://mail.python.org/mailman/listinfo/python-list
Re: What's the standard for code docs?
On Feb 15, 10:59 am, Preston Landers [EMAIL PROTECTED] 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. 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 -- http://mail.python.org/mailman/listinfo/python-list
Re: What's the standard for code docs?
On Feb 20, 9:12 am, Diez B. Roggisch [EMAIL PROTECTED] wrote: 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 Doxygen is your friend! -- http://mail.python.org/mailman/listinfo/python-list
Re: What's the standard for code docs?
On Tue, 19 Feb 2008 16:37:23 -0800, Preston Landers wrote: On Feb 19, 4:31 pm, [EMAIL PROTECTED] 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 -- http://mail.python.org/mailman/listinfo/python-list
Re: What's the standard for code docs?
On 20 Feb, 09:32, Paul McGuire [EMAIL PROTECTED] wrote: 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 -- http://mail.python.org/mailman/listinfo/python-list
Re: What's the standard for code docs?
On Feb 20, 2:32 am, Paul McGuire [EMAIL PROTECTED] wrote: 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. -- http://mail.python.org/mailman/listinfo/python-list
Re: What's the standard for code docs?
On Feb 20, 4:42 am, Marc 'BlackJack' Rintsch [EMAIL PROTECTED] wrote: On Tue, 19 Feb 2008 16:37:23 -0800, Preston Landers wrote: On Feb 19, 4:31 pm, [EMAIL PROTECTED] 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 bayesian= Bayesian() bayesian.train( 'http://groups.google.com/group/comp.lang.python/' ) Training complete. 1.3 seconds elapsed. bayesian.run() Everything! Nobody cares. (setting person.care= 0.0 for person in people) Processing... That's not too bad actually. Where's the bar? -- http://mail.python.org/mailman/listinfo/python-list
Re: What's the standard for code docs?
On Feb 16, 1:56 am, John Nagle [EMAIL PROTECTED] 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? -- http://mail.python.org/mailman/listinfo/python-list
Re: What's the standard for code docs?
HTML. Text-only docs are so last-cen. My sarcasometer is broken today... are you being serious? man serious As opposed to woman serious? [EMAIL PROTECTED]:~$ man -k serious serious: nothing appropriate. -tkc -- http://mail.python.org/mailman/listinfo/python-list
Re: What's the standard for code docs?
On Feb 19, 4:16 pm, [EMAIL PROTECTED] wrote: On Feb 19, 4:12 pm, Preston Landers [EMAIL PROTECTED] wrote: On Feb 16, 1:56 am, John Nagle [EMAIL PROTECTED] 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. -- http://mail.python.org/mailman/listinfo/python-list
Re: What's the standard for code docs?
On Feb 19, 4:21 pm, Preston Landers [EMAIL PROTECTED] wrote: On Feb 19, 4:16 pm, [EMAIL PROTECTED] wrote: On Feb 19, 4:12 pm, Preston Landers [EMAIL PROTECTED] wrote: On Feb 16, 1:56 am, John Nagle [EMAIL PROTECTED] 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 -- http://mail.python.org/mailman/listinfo/python-list
Re: What's the standard for code docs?
On Feb 19, 4:12 pm, Preston Landers [EMAIL PROTECTED] wrote: On Feb 16, 1:56 am, John Nagle [EMAIL PROTECTED] 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 -- http://mail.python.org/mailman/listinfo/python-list
Re: What's the standard for code docs?
On Feb 19, 4:31 pm, [EMAIL PROTECTED] 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. -- http://mail.python.org/mailman/listinfo/python-list
Re: What's the standard for code docs?
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: [EMAIL PROTECTED] (See http://ime.webhop.org for further contact info.) -- http://mail.python.org/mailman/listinfo/python-list
Re: What's the standard for code docs?
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. -- http://mail.python.org/mailman/listinfo/python-list
Re: What's the standard for code docs?
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 -- http://mail.python.org/mailman/listinfo/python-list
