From aa8vb@vislab.epa.gov Tue May 4 13:35:10 1999 From: aa8vb@vislab.epa.gov (Randall Hopper) Date: Tue, 4 May 1999 08:35:10 -0400 Subject: [Doc-SIG] Automatic docs from .py's - what's the latest word? Message-ID: <19990504083510.A48831@vislab.epa.gov> I checked the FAQ, and it suggests gendoc. I went to the gendoc page, and it said use pythondoc. The doc-sig page on Python.org suggests HTMLgen and gendoc, but not pythondoc. Guess my basic question is, which of these are being supported and which have been retired. Also, which do function signature extraction along with grabbing and formatting docstrings? A flat text file or man page is my desired documentation target. Thanks, Randall From Fred L. Drake, Jr." References: <19990504083510.A48831@vislab.epa.gov> Message-ID: <14128.31915.668215.760123@weyr.cnri.reston.va.us> Randall Hopper writes: > I checked the FAQ, and it suggests gendoc. I went to the gendoc page, > and it said use pythondoc. The doc-sig page on Python.org suggests HTMLgen > and gendoc, but not pythondoc. > > Guess my basic question is, which of these are being supported and > which have been retired. Also, which do function signature extraction > along with grabbing and formatting docstrings? A flat text file or man > page is my desired documentation target. Randall, I'm not sure what the current state of pythondoc is; it's definately intended to be a replacement for gendoc. I do plan to spend a little time checking it out at some point before too much longer, but some of the paying projects need to get done at the moment. ;-) I think Daniel Larsson, the author of both gendoc and pythondoc, has been busy with other projects lately and hasn't had time to work on or maintain these packages. Daniel, if you get this, can you give us a brief update regarding your intentions with further development and maintenance of these packages? -Fred -- Fred L. Drake, Jr. Corporation for National Research Initiatives From paul@prescod.net Wed May 19 13:28:21 1999 From: paul@prescod.net (Paul Prescod) Date: Wed, 19 May 1999 07:28:21 -0500 Subject: [Doc-SIG] Tutorial nits Message-ID: <3742AE65.14470EC6@prescod.net> Exhibit 1: > Like in C, the equal sign (‘=’) is used to assign a value to a > variable. The value of an assignment is not written: > >>> width = 20 > >>> height = 5*9 > >>> width * height > 900 Exhibit 2: > This is a rather long string containing\n\ > several lines of text just as you would do in C.\n\ Exhibit 3: > Strings can be subscripted (indexed); like in C, the first > character of a string has subscript (index) 0. I think that these references to C is probably not appropriate now that Python's target user base has expanded beyond C programmers. The tutorial rather implies that you really should know C before attempting Python. Exhibit 4: > Like in Icon, substrings can be specified with the > slice notation: two indices separated by a colon. Not enough people know Icon to risk the same "am I supposed to know that" reaction. How about "As in many languages, ..." For the same reasons I would like to change these two paragraphs: "If you ever wrote a large shell script, you probably know this feeling: you’d love to add yet another feature, but it’s already so slow, and so big, and so complicated; or the feature involves a system call or other function that is only accessible from C . . . Usually the problem at hand isn’t serious enough to warrant rewriting the script in C; perhaps the problem requires variable-length strings or other data types (like sorted lists of file names) that are easy in the shell but lots of work to implement in C, or perhaps you’re not sufficiently familiar with C." "Another situation: perhaps you have to work with several C libraries, and the usual C write/compile/test/re-compile cycle is too slow. You need to develop software more quickly. Possibly perhaps you’ve written a program that could use an extension language, and you don’t want to design a language, write and debug an interpreter for it, then tie it into your application." Actually, at this point in history we probably don't need to justify the concept of a scripting language so we could probably just cut them out. It would be more appropriate, today, to address the Perl refugee^H^H^H^H^H^H^H programmer. I presume that whoever maintains the tutorial is as busy as anyone else. How would I go about helping make changes to it? Should I submit diffs or suggest changes for discussion and then submit diffs? Or just submit textual suggestions? -- Paul Prescod - ISOGEN Consulting Engineer speaking for only himself http://itrc.uwaterloo.ca/~papresco "It's only a movie. People should get a life." - George Lucas (http://www.nypost.com/news/9025.htm) From pearu@ioc.ee Thu May 20 13:06:48 1999 From: pearu@ioc.ee (Pearu Peterson) Date: Thu, 20 May 1999 15:06:48 +0300 (EETDST) Subject: [Doc-SIG] pythonrun.sty release 1.0 Message-ID: Hi! I have released a first complete version of pythonrun.sty: "The pythonrun.sty is a LaTeX2e package that can be used for writing a Latex document if the author wishes to include python code fragments to it. Most importantly, these code fragments can be executed and the results of can be included to Latex output, dynamically. These documents must be compiled with --shell-escape option." The purpose of pythonrun.sty is to ease writing python specific tutorials in Latex. Also User's Guide is available. You can download them from http://koer.ioc.ee/~pearu/python/ Constructive comments and bug reports are welcome. With regards, Pearu Pearu Peterson , MSc, Researcher Department of Mechanics and Applied Mathematics http://koer.ioc.ee/~pearu/ Institute of Cybernetics at Tallinn Technical University Phone: (+372) 6204168 Akadeemia Rd. 21, 12618 Tallinn ESTONIA Fax: (+372) 6204161 *** the nonvalidity of rigorous causality is necessary and not just consistently possible (Heisenberg, 1925) *** From Fred L. Drake, Jr." References: Message-ID: <14149.37302.972006.509555@weyr.cnri.reston.va.us> Pearu Peterson writes: > I have released a first complete version of pythonrun.sty: From a quick look at the documentation, this looks really cool! Hopefully I'll have a chance to play with it some more, but I'm feeling pretty swamped right now. Thanks for letting us know about this! -Fred -- Fred L. Drake, Jr. Corporation for National Research Initiatives From pascucci@cs.utexas.edu Fri May 21 20:59:35 1999 From: pascucci@cs.utexas.edu (pascucci) Date: Fri, 21 May 1999 14:59:35 -0500 Subject: [Doc-SIG] pythondoc Message-ID: <3745BB27.657BE62@cs.utexas.edu> If I have the following statement is included in my module instead when I run pythondoc instead of getting the documentation one of the GL demos is executed. from OpenGL.GL import * I got around this simply changing the statement to (which is better): import OpenGL.GL but this make me wonder how much of the code get executed while generating the documentation. Valerio From Fred L. Drake, Jr." References: <3745BB27.657BE62@cs.utexas.edu> Message-ID: <14149.48394.398830.292625@weyr.cnri.reston.va.us> pascucci writes: > but this make me wonder how much of the code get executed while > generating the documentation. This shouldn't change how much code is executed when your module is imported, but will change the symbols provided by your module (the stuff from OpenGL.GL will not be available directly from your module). I don't know what affect this has on pythondoc; I would *hope* that it doesn't make much if any difference, and suspect that it would actually be able to work faster (it won't have to filter out all the imported symbols). Daniel, are you here to tell us more? -Fred -- Fred L. Drake, Jr. Corporation for National Research Initiatives From pascucci@cs.utexas.edu Mon May 24 06:34:51 1999 From: pascucci@cs.utexas.edu (pascucci) Date: Mon, 24 May 1999 00:34:51 -0500 Subject: [Doc-SIG] links in pythondoc Message-ID: <3748E4FA.C091F56F@cs.utexas.edu> I am using pythondoc and I wonder how can I make links internal to my documentation pages? I do not understand how to use [link to] for referencing other paragraphs in my documentation. It looks like I can write [look at this] where the link is defined by: .. [look at this] THISPOSITION The question is how do I define THISPOSITION? thanks Valerio From pearu@ioc.ee Fri May 28 14:09:37 1999 From: pearu@ioc.ee (Pearu Peterson) Date: Fri, 28 May 1999 16:09:37 +0300 (EETDST) Subject: [Doc-SIG] pythonrun.sty release v1.1 Message-ID: Hi! Please, find from http://koer.ioc.ee/~pearu/python/ a new release of pythonrun.sty v1.1. What's new? One can generate (with included python program) a "static" Latex document with all results of the python calls in it. This "static" version can be used for conversion to a HTML document, for example. Abstract: " The pythonrun.sty is a LaTeX2e package that can be used for writing a Latex document if the author wishes to include python code fragments to it. Most importantly, these code fragments can be executed and the results of can be included to Latex output, dynamically. These Latex documents must be compiled with --shell-escape option. One can also ``distill'' these Latex documents (that is to make them ``static'', and so that the latex->html converters can be applied). The purpose of pythonrun.sty is to ease writing python specific tutorials in LaTeX. " User's Guide is now available also in HTML. Pearu Pearu Peterson , MSc, Researcher Department of Mechanics and Applied Mathematics http://koer.ioc.ee/~pearu/ Institute of Cybernetics at Tallinn Technical University Phone: (+372) 6204168 Akadeemia Rd. 21, 12618 Tallinn ESTONIA Fax: (+372) 6204161 *** the nonvalidity of rigorous causality is necessary and not just consistently possible (Heisenberg, 1925) ***