Mailman 3 November 1996 - Doc-SIG

Re: [PYTHON DOC-SIG] Self-documenting code.. :-)
by Andy Eskilsson Nov. 20, 1996

Nov. 20, 1996

/ "Fred L. Drake" <fdrake(a)CNRI.Reston.VA.US> wrote: | > Michael suggested using the grail textwidget, sounds like a good idea, | > will take a look, but I would like to emphasize that the 'markup' | > language should be the same as the one agreed on for python sources. | | Perhaps the gendoc package or the even the parser module | documentation might provide some useful ideas. Hmm I just thought of it targetting the documentation in the python code, but it could probably be easy to show the code too.. and maybe edit it.. and.. uhm get it written.. :-) A close integration to, or at least look at gendoc is a good idea.. if it is what I think it is.. /Andy -- Hi I am an alien .sig, and at the | Unsolicited commercial email is moment I am having sex to your mind,|subject to an archival fee of $400. by looking at your smile I can see |See www.fukt.hk-r.se/~flognat/mail that you like it. | for more info. ================= DOC-SIG - SIG for the Python Documentation Project send messages to: doc-sig(a)python.org administrivia to: doc-sig-request(a)python.org =================

2 1

Re: [PYTHON DOC-SIG] Self-documenting code.. :-)
by Andy Eskilsson Nov. 20, 1996

Nov. 20, 1996

Thinking a bit more.. what would be nice is some kind of browser that could be used for example by developers, they do 'helpbrowse script.py', up pops a window that contains the 'master' doc-string (maybe 'folded' in some way) of script.py, and from there links to the function/class doc-strings, also links to imported modules, so they can be browsed. Hopefully this is done so it is possible to use it from a unix-prompt, not only under some window manager. Michael suggested using the grail textwidget, sounds like a good idea, will take a look, but I would like to emphasize that the 'markup' language should be the same as the one agreed on for python sources. /Andy p.s. Hmm people want to have the documentation outside the python code, maybe add ability to browse external files too, sort of, tada.. the problem with documentation for 'external' modules is solved.. hmm -- Hi I am an alien .sig, and at the | Unsolicited commercial email is moment I am having sex to your mind,|subject to an archival fee of $400. by looking at your smile I can see |See www.fukt.hk-r.se/~flognat/mail that you like it. | for more info. ================= DOC-SIG - SIG for the Python Documentation Project send messages to: doc-sig(a)python.org administrivia to: doc-sig-request(a)python.org =================

2 1

[PYTHON DOC-SIG] Self-documenting code.. :-)
by Andy Eskilsson Nov. 19, 1996

Nov. 19, 1996

I don't know if this has been discussed before (I just joined the list) but would it be possible to do some kind of browser for X and uhm.. well curses sort of would be fine? What I really want to say is that most X applications has a help-menu.. and well there already (hopefully) exists documentation for the application in the __doc__ strings, so why not use the __doc__ string when generating the help dialog? Of course this should use the standards the rest of the docs are using.. An example of this have I done in my Regexper application, just trying it out, check http://www.fukt.hk-r.se/~flognat/hacks/Regexer3.py. Another way to use this could also be text displayed when issuing a application -h, instead of needing a bunch of print statements, it could print out a selection of the __doc__ strings? This is maybe easy to do for one app, but it would maybe be nice having a good browser that people can use, and maybe also the possibility to not only grab the modules doc string, but the other doc strings belonging to classes/imported modules/functions? /Andy -- Hi I am an alien .sig, and at the | Unsolicited commercial email is moment I am having sex to your mind,|subject to an archival fee of $400. by looking at your smile I can see |See www.fukt.hk-r.se/~flognat/mail that you like it. | for more info. ================= DOC-SIG - SIG for the Python Documentation Project send messages to: doc-sig(a)python.org administrivia to: doc-sig-request(a)python.org =================

1 0

[PYTHON DOC-SIG] Re: [PYTHON MATRIX-SIG] Alpha release of new tutorial for 1.0a5
by da＠maigret.cog.brown.edu Nov. 8, 1996

Nov. 8, 1996

In my announcement of the alpha tutorial for the numeric extension, I wrote: > > And there are HTML, DVI, TeX, Info, Text and PS versions (TIM is > > pretty cool really!). Which prompted Geoffrey Furnish to ask in email: > BTW, what is TIM? Can you give me a brief low-down on it? Can it do > math like tex/latex? TIM is a tool developed by Bill Janssen as part of the ILU project at Xerox PARC, but independent of ILU. Some documentation can be found at: ftp://ftp.parc.xerox.com/pub/ilu/2.0/20a8-manual-html/manual_17.html#SEC275 The key sentence is: TIM is essentially a superset of the GNU texinfo language, version 2. It adds several features to allow more precise discrimination of semantics when documenting software systems. You should be familiar with the basic texinfo system first. I am still a novice at it, so I'm not sure about it possibilities. I suspect that one can insert TeX commands in it, and they'll come out fine in the TeX mode. I suspect also that they won't come out at all in HTML mode. I chose it because it seemed reasonable. I'm probably using very few features of TIM which aren't part of Texinfo. I also thought that since we're looking for a common documentation format, this could be somewhat of a test for TIM. For most of the python modules, I think TIM would be good enough. For the scientific extensions which are bound to arrive in droves =), it'd be nice to have one which allowed math like LaTeX, but also allowed it to be displayed in HTML form. This makes me think that an interface between a markup language like TIM's and a system like Ka-Ping Yee's system would be nice. It's a big project though, and one I'm not volunteering for. Thoughts anyone? --david [I'm sending this to matrix-sig, doc-sig and Bill Janssen and Ping since they all seem relevant. Maybe followups should just go to doc-sig?]. PS: One of the reasons I like TIM is that it seems it shouldn't be too hard to do a reasonable TIM->SGML conversion someday, when the tools become available. ================= DOC-SIG - SIG for the Python Documentation Project send messages to: doc-sig(a)python.org administrivia to: doc-sig-request(a)python.org =================

4 3

[PYTHON DOC-SIG] Re: [PYTHON MATRIX-SIG] Where to go (was Numerical Recipes)
by friedric＠rose.rsoc.rockwell.com Nov. 7, 1996

Nov. 7, 1996

|> From: da(a)maigret.cog.brown.edu (David Ascher) |> Subject: Re: [PYTHON MATRIX-SIG] Where to go (was Numerical Recipes) |> To: jhauser(a)ifm.uni-kiel.de (janko hauser) |> Date: Sun, 20 Oct 1996 15:30:32 -0400 (EDT) |> |> Clearly this would make most sense if all Python docs were available in |> a TIM-like format. Maybe it's time to ask the DOC-SIG what's up. The |> Reference manual has been converted to FrameMaker, which might actually |> allow conversion to SGML and from there TIM? The other manuals were |> last I checked available in info format (in fact it's with the library |> reference in mind that I wrote the `ihelp' module, when some users were |> complaining that Python had lousy help facilities compared to |> matlab...). |> |> --david |> It should be made clear that the Language Reference and Tutorial are the only docs converted to FrameMaker. The Lib Ref is still up in the air as to format. The last view I heard was that it should be written in a very easy system that's text-based and assembled into it's entirety with some higher level tools. TIM looks to be the odds on favorite here but there needs to be a whole lot more concurrence among module writers. The structured text standard for doc strings needs to be considered and incorporated as well. A TIM formatter for gendoc is an obvious approach. ================= DOC-SIG - SIG for the Python Documentation Project send messages to: doc-sig(a)python.org administrivia to: doc-sig-request(a)python.org =================

4 4

[PYTHON DOC-SIG] Re: Inclusion of contributed modules
by Andrew Kuchling Nov. 7, 1996

Nov. 7, 1996

Guido van Rossum wrote (in comp.lang.python): > A good start would probably to have a standard infrastructure to build > third-party extensions. How about having them inside a subdirectory > Extensions in the Python toplevel directory, if they are relatively IMHO, all non-standard modules should live in such an Extensions/ subdirectory; I've tried to do this with the sizable extensions that I write. ILU's really a rare special case, since it's much more than simply a Python module. Another important point to consider is documentation for extension modules; if possible, lib*.tex files should be automatically included in the library reference. I hate the fact that many modules come with READMEs The following script looks through the directories in sys.path for anything that can be imported, cross-references them with the files in Doc/, and produces TeX code for a customized library reference. The only thing needed is to have it walk through subdirectories of Extensions/, find any lib*.tex files, and generate appropriate TeX code. (Perhaps it shouldn't list the standard modules at all; then adding a new module won't require reprinting the entire Library Reference, but only a much smaller custom modules document.) Andrew Kuchling amk(a)magnet.com # Generate custlib.tex, which is a site-specific library document. # Phase I: list all the things that can be imported import glob, os, sys, string modules={} for modname in sys.builtin_module_names: modules[modname]=modname for dir in sys.path: # Look for *.py files filelist=glob.glob(os.path.join(dir, '*.py')) for file in filelist: path, file = os.path.split(file) base, ext=os.path.splitext(file) modules[string.lower(base)]=base # Look for shared library files filelist=(glob.glob(os.path.join(dir, '*.so')) + glob.glob(os.path.join(dir, '*.sl')) + glob.glob(os.path.join(dir, '*.o')) ) for file in filelist: path, file = os.path.split(file) base, ext=os.path.splitext(file) if base[-6:]=='module': base=base[:-6] modules[string.lower(base)]=base # Minor oddity: the types module is documented in libtypes2.tex if modules.has_key('types'): del modules['types'] ; modules['types2']=None # Phase II: find all documentation files (lib*.tex) # and eliminate modules that don't have one. docs={} filelist=glob.glob('lib*.tex') for file in filelist: modname=file[3:-4] docs[modname]=modname mlist=modules.keys() mlist=filter(lambda x, docs=docs: docs.has_key(x), mlist) mlist.sort() mlist=map(lambda x, docs=docs: docs[x], mlist) modules=mlist # Phase III: write custlib.tex # Write the boilerplate # XXX should be fancied up. print """\documentstyle[twoside,11pt,myformat]{report} \\title{Python Library Reference} \\input{boilerplate} \\makeindex % tell \\index to actually write the .idx file \\begin{document} \\pagenumbering{roman} \\maketitle \\input{copyright} \\begin{abstract} \\noindent This is a customized version of the Python Library Reference. \\end{abstract} \\pagebreak {\\parskip = 0mm \\tableofcontents} \\pagebreak\\pagenumbering{arabic}""" for modname in mlist: print "\\input{lib%s}" % (modname,) # Write the end print """\\input{custlib.ind} % Index \\end{document}""" ================= DOC-SIG - SIG for the Python Documentation Project send messages to: doc-sig(a)python.org administrivia to: doc-sig-request(a)python.org =================

1 0