From kmcdona@watson.wustl.edu Tue Feb 17 19:06:13 1998 From: kmcdona@watson.wustl.edu (Ken McDonald) Date: Tue, 17 Feb 1998 13:06:13 -0600 (CST) Subject: [DOC-SIG] Status of documentation effort? Message-ID: Could someone please email me the current status of the documentation tools effort? I notice the copy of gendoc on the site is from 1996! Thanks, Ken ======================================== Kenneth McDonald Genome Sequencing Center Washington University School of Medicine Phone: 314-286-1831 ======================================== _______________ DOC-SIG - SIG for the Python Documentation Project send messages to: doc-sig@python.org administrivia to: doc-sig-request@python.org _______________ From Robin.K.Friedrich@USAHQ.UnitedSpaceAlliance.com Tue Feb 17 19:38:02 1998 From: Robin.K.Friedrich@USAHQ.UnitedSpaceAlliance.com (Friedrich, Robin K) Date: Tue, 17 Feb 1998 13:38:02 -0600 Subject: [DOC-SIG] Status of documentation effort? Message-ID: There has never been a coordinated doc-sig effort started for automated documentation generation ala gendoc. Currently gendoc has been patched to work in 1.5 by it's author Daniel Larsson. I have wanted to start one though. Hopefully recent interest indicates that we would get some substantial efforts from folks on this list should we start one. So... Dan and I have bounced some preliminary thoughts on just how such a gendoc "next generation" (1.0) tool should work. I'd like to propose the following and start hammering on a detailed design for gendoc NG. If the design proves to be sufficiently modular we'll be able to divide up the work among several people. There's a lot of work here but I'm confident we can come up with something working/nice in a couple months. Remember, this is a draft for discussion, so pile on the constructive comments;-) GENDOC 1.0 Design Requirements Works for Python 1.5 and up. (takes advantage of new features like issubclass()) Parsing using new re module. Supports 1.5 Package scheme and is written as a package. Uses import method to extract info. Uses Structured Text as standard for doc string parsing. (Although we have to decide on the prototype information format.) Supports C modules/types that have doc strings. Generates abstract information structure which can be tapped by rendering classes to generate customizable output. Abstract structure is picklable using cPickle. (Speeds tailoring the rendered output while keeping the input the same.) Merge output from independant runs. (simple using prior pickle files) Must run on Unix, Win32, and Mac. QUESTIONS - How to do function prototypes? Resort to Python source parsing module? GENDOC 1.0 Architecture Objects: Package, Module, Class, Function, Method, Attribute, Argument, Documentation, Hyperlinks, ... Each of these will store information derived from their doc strings and other sources. Parse doc strings with structured text and populate Documentation class instance for each doc string. Class objects contain instances from Method, Attribute, Documentation, along with base class references. Class and Module objects also get added to separate heirarchy structures supporting dependancy diagrams. Render sub-packages for: HTMLgen2/CSS1, XML/XSL, WinHelp, MIF, text, etc. Renderers are passed the full structure object and walk the tree generating the appropriate output. Features to help tailor the content and ordering of output may be included in a base class AbstractRenderer. A renderer which translates the data into a structure suitable for import into a programming environment tool like PTUI might me nice too. This obviously moves much of the complexity to the rendering classes but with helper base classes and good examples people ought to be able to write their own without too much trouble. The next step would be to define the doc objects' interfaces. A quick shot: class Package: def filename(): ... Or as separate functions(def functions():) -Yes def modules(): # can a package have functions? def subpackages(): def parent(): # None, if global def name(): def documentation(): # Returns Documentation object class Documentation: def brief(): # the brief one liner def body(): # return Body object def examples(): # return example text class Body: # return structure doc string as a list of # objects representing marked up text/hypertext class Module: def filename(): def children(): def parent(): def name(): def documentation(): class Function: def parent(): # the function's module def name(): def arguments(): def documentation(): def type(): #?? built-in or "normal" ---Jim F would go ballistic:-) def implementation(): # let's call it this. # Can we differentiate between builtin vs. extension? def return_type(): #?? If we can deduce this from a prototype doc # OK class Class: def parent(): def name(): def baseclasses(): def methods(): def documentation(): class Method(Function): # Basically the same thing, except parent() def parent(): # returns a Class (?) ---yes, class Attribute: def parent(): def name(): def type(): # type(attr) def value(): # If there is a notation in the module's docstring # to document attributes, then: def documentation(): class Argument: #--- how to handle *args and **kw ? def parent(): # Function object def name(): def type(): def default(): def documentation(): _______________ DOC-SIG - SIG for the Python Documentation Project send messages to: doc-sig@python.org administrivia to: doc-sig-request@python.org _______________ From Daniel.Larsson@vasteras.mail.telia.com Tue Feb 17 19:34:06 1998 From: Daniel.Larsson@vasteras.mail.telia.com (Daniel Larsson) Date: Tue, 17 Feb 1998 20:34:06 +0100 Subject: [DOC-SIG] Status of documentation effort? References: Message-ID: <34E9E62D.E8B023@vasteras.mail.telia.com> This is a multi-part message in MIME format. --------------C161904B2B6A499C6370B468 Content-Type: text/plain; charset=us-ascii Content-Transfer-Encoding: 7bit Robin Friedrich and I has just started talking a bit how we would like gendoc 1.0 to look like (last week, actually). We're planning to take the discussion to the list real soon now. Don't know of other efforts. Ken McDonald wrote: > Could someone please email me the current status of the documentation > tools effort? I notice the copy of gendoc on the site is from 1996! > > Thanks, > Ken --------------C161904B2B6A499C6370B468 Content-Type: text/x-vcard; charset=us-ascii; name="vcard.vcf" Content-Transfer-Encoding: 7bit Content-Description: Card for Daniel Larsson Content-Disposition: attachment; filename="vcard.vcf" begin: vcard fn: Daniel Larsson n: Larsson;Daniel email;internet: Daniel.Larsson@vasteras.mail.telia.com x-mozilla-cpt: ;0 x-mozilla-html: TRUE version: 2.1 end: vcard --------------C161904B2B6A499C6370B468-- _______________ DOC-SIG - SIG for the Python Documentation Project send messages to: doc-sig@python.org administrivia to: doc-sig-request@python.org _______________ From poinot@onera.fr Wed Feb 18 10:21:35 1998 From: poinot@onera.fr (Marc Poinot) Date: Wed, 18 Feb 1998 11:21:35 +0100 Subject: [DOC-SIG] Status of documentation effort? References: Message-ID: <34EAB62F.2781@onera.fr> I'm a newcommer in the group, I've read your status and I have a single simple question: - What is the purpose of the doc? This may have been discussed before...my goals in documenting code are: 1- Interface How to use the module, when, args meaning, design tips... With an interface langage like C++, ADA, etc... I can document the interface part with such informations. This is public information. 2- Maintenance How to deal with the implementation? The why of the design the description of private parts. In a C++ or ADA code I put this information in the bodies. This is the private information. I can document Python code for the point [2]. As a matter of fact, I've got a practical problem with [1]: How to provide the users with a public interface (as doc)? Something like IDL (but I don't want IDL, I want pure Python!)? Is it possible to imagine two doc levels ? Here are my remarks about your requirements: Friedrich, Robin K wrote: > > GENDOC 1.0 Design Requirements > ... > Uses import method to extract info. > For the point [1], I guess the import is for the doc generation. But this implies two set of files, the code and the doc. Can we imagine to have a simple (raw dumb textual) description of the services of a class using a self-builting method in the module itself? (?? !) ? > Must run on Unix, Win32, and Mac. > NT (?) > Render sub-packages for: HTMLgen2/CSS1, XML/XSL, WinHelp, MIF, text, > etc. etc=LaTeX > Renderers are passed the full structure object and walk the tree > generating > the appropriate output. Features to help tailor the content and ordering > of output > may be included in a base class AbstractRenderer. A renderer which > translates the > data into a structure suitable for import into a programming environment > tool like > PTUI might me nice too. > Use for an Index? > class Module: > def filename(): > def children(): > def parent(): > def name(): > def documentation(): > def ShortDocumentationForOtherModulesWhichImportMe(): Or does it take place into a doc format standard? Marcvs [alias Once again, our problem is how to provide a public embedded documentation, any hints are bienvenus] _______________ DOC-SIG - SIG for the Python Documentation Project send messages to: doc-sig@python.org administrivia to: doc-sig-request@python.org _______________ From Robin.K.Friedrich@USAHQ.UnitedSpaceAlliance.com Wed Feb 18 13:44:19 1998 From: Robin.K.Friedrich@USAHQ.UnitedSpaceAlliance.com (Friedrich, Robin K) Date: Wed, 18 Feb 1998 07:44:19 -0600 Subject: [DOC-SIG] Status of documentation effort? Message-ID: >---------- >From: Marc Poinot[SMTP:poinot@onera.fr] >Sent: Wednesday, February 18, 1998 4:21 AM >To: doc-sig@python.org >Subject: Re: [DOC-SIG] Status of documentation effort? > >I'm a newcommer in the group, I've read your status and I have a >single simple question: > >- What is the purpose of the doc? > >This may have been discussed before...my goals in documenting code are: Pretty much the same goals as the rest of us:-) gendoc in the past has restricted itself to the information in the doc strings and the meta-information gathered from the module. This traditionally will contain just the public or user level documentation. Gendoc is targeted at generating this level. Maintenance information is generally found in comments rather than doc strings. The maintainer of the code is obviously looking at the source anyway, while if we do our job right in generating user documentation the *users* of the code won't have to. > ... >I can document Python code for the point [2]. >As a matter of fact, I've got a practical problem with [1]: >How to provide the users with a public interface (as doc)? >Something like IDL (but I don't want IDL, I want pure Python!)? >Is it possible to imagine two doc levels ? Yes. Let's restrict ourselves to point[1] though for gendoc. > >Here are my remarks about your requirements: > >Friedrich, Robin K wrote: >> >> GENDOC 1.0 Design Requirements >> >... >> Uses import method to extract info. >> >For the point [1], I guess the import is for the doc generation. >But this implies two set of files, the code and the doc. Can we >imagine to have a simple (raw dumb textual) description of >the services of a class using a self-builting method in the >module itself? (?? !) ? I don't think that will be as practical as having a tool to run over your source tree. > >> Must run on Unix, Win32, and Mac. >> >NT (?) That's Win32 - so yes NT. This one's a given if we write everything in Python. > >> Render sub-packages for: HTMLgen2/CSS1, XML/XSL, WinHelp, MIF, text, >> etc. >etc=LaTeX OK you just volunteered;-) for the LaTeX renderer. > >> Renderers are passed the full structure object and walk the tree >> generating >> the appropriate output. Features to help tailor the content and ordering >> of output >> may be included in a base class AbstractRenderer. A renderer which >> translates the >> data into a structure suitable for import into a programming environment >> tool like >> PTUI might me nice too. >> >Use for an Index? Yes. Have you looked at gendoc 0.6 output? check out: http://starship.skyport.net/crew/friedrich/HTMLgen/html/index.html > >> class Module: >> def filename(): >> def children(): >> def parent(): >> def name(): >> def documentation(): >> > def ShortDocumentationForOtherModulesWhichImportMe(): > >Or does it take place into a doc format standard? > >Marcvs [alias Once again, our problem is how to provide a public >embedded > documentation, any hints are bienvenus] Also required reading in this discussion will be the structured text standard. http://www.python.org/sigs/doc-sig/ > > _______________ DOC-SIG - SIG for the Python Documentation Project send messages to: doc-sig@python.org administrivia to: doc-sig-request@python.org _______________ From poinot@onera.fr Wed Feb 18 15:40:44 1998 From: poinot@onera.fr (Marc Poinot) Date: Wed, 18 Feb 1998 16:40:44 +0100 Subject: [DOC-SIG] Status of documentation effort? References: Message-ID: <34EB00FC.41C6@onera.fr> > >For the point [1], I guess the import is for the doc generation. > >But this implies two set of files, the code and the doc. Can we > >imagine to have a simple (raw dumb textual) description of > >the services of a class using a self-builting method in the > >module itself? (?? !) ? > I don't think that will be as practical as having a tool to run over > your source tree. I'd like something self contained (as thin as possible). I think it's better to avoid to require a package which requires a package, which requires a package... I mean something like: Python 1.4 (Jun 25 1997) [C] Copyright 1991-1995 Stichting Mathematisch Centrum, Amsterdam >>> import HTgenML >>> HTgenML.public() ...stuff... > >> Render sub-packages for: HTMLgen2/CSS1, XML/XSL, WinHelp, MIF, text, > >> etc. > >etc=LaTeX > OK you just volunteered;-) for the LaTeX renderer. > > No, no, I was kidding, crucifixion... of course! Why not, I can be a base class, and you may find more specialized LaTeX user than me later ;) Marcvs [alias TODO: read Python tutorial, LaTeX tutorial, HTMLgen tutorial, Berlitz English tutorial, doc-sig archive!] _______________ DOC-SIG - SIG for the Python Documentation Project send messages to: doc-sig@python.org administrivia to: doc-sig-request@python.org _______________ From MHammond@skippinet.com.au Wed Feb 18 23:41:26 1998 From: MHammond@skippinet.com.au (Mark Hammond) Date: Thu, 19 Feb 1998 10:41:26 +1100 Subject: [DOC-SIG] Status of documentation effort? Message-ID: <01bd3cc6$ba9b8f30$ff01a8c0@skippy> >There has never been a coordinated doc-sig effort started for automated >documentation generation ala gendoc. Currently gendoc has been patched >to work in 1.5 by it's author Daniel Larsson. I have wanted to start one >though. Hopefully recent interest indicates that we would get some >substantial efforts from folks on this list should we start one. So... The list looks very good. Regarding the winhelp renderer, it is very likely this wont be needed with the new MS "htmlhelp" stuff. I'll try and look into this and see what the impact is. But my main point of writing is to outline one of my key requirements before I could move to gendoc full-time. I really, really, really would like a technique for defining cross-references in the documentation strings. At the moment URL's are OK, but it is nigh on impossible to have "func1" contain a documentation cross-reference to "func2" - there is no URL for "func2" - it is being generated by the same process doing func1. My main objective is to replace all of the "winhelp" documentation I have with "gendoc" generated. However, most of the existing winhelp documentation is formatted as a "reference guide", and cross-references are an absolute necessity. Unfortunately, this is not as trivial as it sounds - but it is not too hard either. Is there general support for a feature like this? [I did make some hacks to gendoc to support this, but the patches were too wide-reaching for me to post back, and no one else except me really seemed to care about this feature...] Mark. _______________ DOC-SIG - SIG for the Python Documentation Project send messages to: doc-sig@python.org administrivia to: doc-sig-request@python.org _______________ From mcfletch@golden.net Thu Feb 19 06:23:24 1998 From: mcfletch@golden.net (Mike Fletcher) Date: Thu, 19 Feb 1998 01:23:24 -0500 Subject: [DOC-SIG] URI Schemes In-Reply-To: <01bd3cc6$ba9b8f30$ff01a8c0@skippy> Message-ID: <3.0.2.32.19980219012324.00e094d0@pop.golden.net> So, anyone got a decent URI scheme for Python elements? Preferably something that will handle: fully-qualified (universally valid) URI's... something like /mcf/pars/andgrp#AndGrp.consume /mcf/pars/andgrp /mcf/pars/orgrp#OrGrp Basically, should be able to say: from mcf.pars.andgrp import AndGrp and then get the correct attribute off AndGrp? Requires that the processing script know the sys.path under which the files will be processed, that is, the script needs to know what the root of the hierarchy is for the sets of relative URI's (context sensitive)... something like #OrGrp.posopt_consume # in same module ./orgrp#OrGrp.consume # method in module in same package ../utils#dummy # module in sibling package consume # method of class OrGrp OrGrp.consume # class method of module orgrp orgrp # module of package pars ...yada catching broken links (optional) These obviously aren't the perfect URI schemes, anyone have any better ones? We would want them to be easily typed, and hopefully easily recognised both by the code reader and the system. Well, off to sleep, enjoy all, Mike ________________________________ M i k e C . F l e t c h e r mcfletch@golden.net http://www.golden.net/~mcfletch/ ________________________________ Design, Consultation, Training _______________ DOC-SIG - SIG for the Python Documentation Project send messages to: doc-sig@python.org administrivia to: doc-sig-request@python.org _______________ From Robin.K.Friedrich@USAHQ.UnitedSpaceAlliance.com Thu Feb 19 13:57:59 1998 From: Robin.K.Friedrich@USAHQ.UnitedSpaceAlliance.com (Friedrich, Robin K) Date: Thu, 19 Feb 1998 07:57:59 -0600 Subject: [DOC-SIG] Xrefs (was)Status of documentation effort? Message-ID: >---------- >From: Mark Hammond[SMTP:MHammond@skippinet.com.au] >But my main point of writing is to outline one of my key requirements before >I could move to gendoc full-time. > >I really, really, really would like a technique for defining >cross-references in the documentation strings. At the moment URL's are OK, >but it is nigh on impossible to have "func1" contain a documentation >cross-reference to "func2" - there is no URL for "func2" - it is being >generated by the same process doing func1. Acknowledged. I'll add that to the list of requirements. > >...Unfortunately, this is not as trivial as it sounds - but it is not too >hard >either. Is there general support for a feature like this? Not yet. We'll have to cook up one. I propose extending the footer syntax (the one prefixed with two dots) to specify a cross-reference token. Something like: """ I'm here in the middle of the doc string for class Fun but I would like to mention that this class is used to populate the container class [Party]. And at the end of the doc string... .. [Party] in module: Disco """ In this case gendoc would look for documented object 'Party' in module Disco. We'd have to have other context indicators like package and then maybe bore down to the containing namespace by slash separated names, e.g. .. [method] in package: Dance/Disco/Party to completely specify the Party.method cross reference. A problem crops up if you want to reference two objects of the same name in different namespaces. Ideas? > > > _______________ DOC-SIG - SIG for the Python Documentation Project send messages to: doc-sig@python.org administrivia to: doc-sig-request@python.org _______________ From Fred L. Drake, Jr." References: Message-ID: <199802191414.JAA12973@weyr.cnri.reston.va.us> Friedrich, Robin K writes: ... > .. [Party] in module: Disco > """ > In this case gendoc would look for documented object 'Party' in module > Disco. We'd have to have other context indicators like package and then > maybe bore down to the containing namespace by slash separated names, > e.g. > .. [method] in package: Dance/Disco/Party > > to completely specify the Party.method cross reference. A problem crops > up if you want to reference two objects of the same name in different > namespaces. Ideas? Robin, Why not: .. [Party] in module: Dance.Disco.Party for module attributes, and require that the module name be fully qualified? Or that using just one name is searched for in "current package, global package" order (meaning the "current package" needs to be known, which is not unreasonable). Using slashes instead of dots is adding new & unnecessary syntax; dots work well in Python, and these are references to Python objects. Tools can use whatever internal representations are needed easily enough. We can generalize this a little by using the form: .. [name] in [:] The colon should be omitable (new word?!); some people may like it for presentation, but it carries no content. Identifying the footer line should be done only on the leading ".." and brackets around the name. should allow checking the reference to be sure it matches what's found at the target; I expect "class", "module", and "package" might be usable. Perhaps allow "namespace" to signify an namespace of arbitrary type. Overall, this seems like a very reasonable notation. -Fred -- Fred L. Drake, Jr. fdrake@cnri.reston.va.us Corporation for National Research Initiatives 1895 Preston White Drive Reston, VA 20191-5434 _______________ DOC-SIG - SIG for the Python Documentation Project send messages to: doc-sig@python.org administrivia to: doc-sig-request@python.org _______________ From Robin.K.Friedrich@USAHQ.UnitedSpaceAlliance.com Thu Feb 19 15:30:02 1998 From: Robin.K.Friedrich@USAHQ.UnitedSpaceAlliance.com (Friedrich, Robin K) Date: Thu, 19 Feb 1998 09:30:02 -0600 Subject: [DOC-SIG] Xrefs Message-ID: >From: Fred L. Drake[SMTP:fdrake@cnri.reston.va.us] >Robin, > Why not: > > .. [Party] in module: Dance.Disco.Party > >for module attributes, and require that the module name be fully >qualified? Or that using just one name is searched for in "current >package, global package" order (meaning the "current package" needs to >be known, which is not unreasonable). On second thought, requiring full qualification is probably the best since it requires the least new understanding on the part of the user. And when reading the code this will be the most helpful as relying on the tool's searching rules won't help the reader of the source. And yes the . separator is more appropriate. > We can generalize this a little by using the form: > > .. [name] in [:] > >The colon should be omitable (new word?!); some people may like it for >presentation, but it carries no content. Identifying the footer line I do like it for presentation and to help disambiguate the namespace type from the namespace name itself. Just because it carries no information content doesn't mean it's not mentally useful. And in general I don't like optional tokens. >should be done only on the leading ".." and brackets around the name. > should allow checking the reference to be sure it >matches what's found at the target; I expect "class", "module", and >"package" might be usable. Perhaps allow "namespace" to signify an >namespace of arbitrary type. > Overall, this seems like a very reasonable notation. Agreed. Robin > > > _______________ DOC-SIG - SIG for the Python Documentation Project send messages to: doc-sig@python.org administrivia to: doc-sig-request@python.org _______________ From Fred L. Drake, Jr." References: Message-ID: <199802191607.LAA14018@weyr.cnri.reston.va.us> Friedrich, Robin K writes: > On second thought, requiring full qualification is probably the best > since it requires the least new understanding on the part of the user. > And when reading the code this will be the most helpful as relying on > the tool's searching rules won't help the reader of the source. > > And yes the . separator is more appropriate. ... > I do like it for presentation and to help disambiguate the namespace > type from the namespace name itself. Just because it carries no > information content doesn't mean it's not mentally useful. And in Fully-qualified names is fine by me. I'd rather not have to use the colon; it seems distinctly different from the way things get described in the Python Library Reference (where phrases like "in module frobnaltz" are added to index entries, for instance). But I could live with it. It sounds like we're in reasonable agreement on this. Comments from anyone else? -Fred -- Fred L. Drake, Jr. fdrake@cnri.reston.va.us Corporation for National Research Initiatives 1895 Preston White Drive Reston, VA 20191-5434 _______________ DOC-SIG - SIG for the Python Documentation Project send messages to: doc-sig@python.org administrivia to: doc-sig-request@python.org _______________ From richard.jones@bom.gov.au Thu Feb 19 22:48:18 1998 From: richard.jones@bom.gov.au (Richard Jones) Date: Thu, 19 Feb 1998 22:48:18 +0000 Subject: [DOC-SIG] Xrefs In-Reply-To: Message from "Fred L. Drake" of 1998-Feb-19 11:7:22, <199802191607.LAA14018@weyr.cnri.reston.va.us> Message-ID: <199802192248.WAA00392@mage.ho.bom.gov.au> "Fred L. Drake" wrote: > Comments from anyone else? I like it - and I like having the colon optional. I agree that it feels more natural to just have "in module foo.bar" rather than "in module: foo.bar" - it just scans a little easier. Richard _______________ DOC-SIG - SIG for the Python Documentation Project send messages to: doc-sig@python.org administrivia to: doc-sig-request@python.org _______________ From MHammond@skippinet.com.au Mon Feb 23 03:38:13 1998 From: MHammond@skippinet.com.au (Mark Hammond) Date: Mon, 23 Feb 1998 14:38:13 +1100 Subject: [DOC-SIG] Xrefs Message-ID: <01bd400c$78648240$0a01a8c0@skippy.skippinet.com.au> [Fred wrote] > It sounds like we're in reasonable agreement on this. > Comments from anyone else? Of course :-) Sorry about their delay tho... Before I start, I should state my "position". IMO, if we do a good enough job with gendoc, people will _generally_ use the documentation generated, rather than attempting to browse the sources directly. Therefore, I would prefer to sacrifice readability for functionality - ie, if we need to make _small_ parts of the docstring scan not so well for a human, but it significantly enhances the gendoc output, then I am all for it. Just MO of course - I am sure others do not agree. OK: The proposal is: > .. [name] in [:] eg: """ see also foo in function mymodule """ My main problem with it is that it only allows you to insert a hyperling to object "foo" by using the word "foo". What if I wanted the documentation to have a hyperlink to an object, but I want the hyperlink text to be something other than the object name - say a phrase or complete sentence. And I also cant see what "namespace-type" gives us? The name itself determines the object and if we use Python's normal scoping rules, then a given name can mean exactly one object. If you get a different object than you expect, I would consider it a "documentation bug" in the same way it would be a bug in code. Rudimentary testing of the generated documentation would find it. Id find it ironic if the Python documentation was more type-safe than Python itself :-) However, I _could_ see the being useful for other reasons. [Brainstorm] If ommitted, it means "Python". You could use it to reference source files themselves - eg, . Eg, a namespace could be "sourcefile", and the formatting tools could make the appropriate hyperlink You could allow "plug-in" namespaces. Eg, if may be possible to allow me to develop a "win32api" namespace, so I could insert cross-references into the Microsoft API documentation. With this moving to HTML itself, it may be quite feasable. You could provide a namespace called "html" and replace the existing hyperlink stuff with this. [/Brainstorm] As a poor starting point, I would consider: It does not screw human scanning completely, and infact may help with the highlighting that a link exists, even if you can't click to see it. Here is an example of some docstrings that I could forsee myself writing with this functionality :-) """ ... this example makes use of the It is very similar to the . It makes very heavy use of the bizarre , and the bizarre feature """ Or am I way off track? Here is another curly one for you all - if we support cross-references, should we also support generating and reading "map" files? If we did, it would be possible for a whole suite of seperately generated gendoc code to be completely cross-referenced and indexed. Something like this will be a necessity (ok - very handy :-) if we are ever to allow someone to press the "help" key in a Python IDE, and have it find the correct keyword, or have people reference each others packages. Eeek!! But worth at least thinking about for a few seconds :-) FWIW, I would be happy to contribute in this general xref area if we can nut out general agreement... [Im also going to want to be able to plug in my own "parser", "scanner", "importer" or whatever you call the thing that "collects" the documentation info into the Python structures. I have lots of C++ code in a "special" format that I could then use, and drop my winhelp files alltogether... If you have seen my Windows stuff, all the winhelp files are generated purely from C++ sources! But that is a different issue. :-)] Mark. _______________ DOC-SIG - SIG for the Python Documentation Project send messages to: doc-sig@python.org administrivia to: doc-sig-request@python.org _______________ From mcfletch@golden.net Mon Feb 23 16:45:11 1998 From: mcfletch@golden.net (Mike Fletcher) Date: Mon, 23 Feb 1998 11:45:11 -0500 Subject: [DOC-SIG] Xrefs In-Reply-To: <01bd400c$78648240$0a01a8c0@skippy.skippinet.com.au> Message-ID: <3.0.2.32.19980223114511.00e0f2b8@pop.golden.net> I too would like to see a form that lets the documentation "read". But I think the pattern: is a little foreign-seeming, why not just go for what's already the defacto standard on the net? linktext or even: linktext/ or (going the other way): linktext or (getting ridiculous now): linktext Which would give: """ ... this example makes use of the win32com client support It is very similar to the other sample in othersample.py. It makes very heavy use of the bizarre Python feature spam, and the bizarre feature eggs that the win32 API provides """ I know, I know, not really in keeping with the "structured text" philosophy (or, rather, the consistently formatted text philosophy that is called structured text) , but I tend to think it's a decent approach to the problem (and one that's rather well understood by now), and one where tools are rather easy to come by. Well, enjoy all, Mike "Mark Hammond" : ... >As a poor starting point, I would consider: > ... >""" ... this example makes use of the support|win32com.client> > It is very similar to the othersample.py|win32com.demos.othersample.py|sourcefile>. > > It makes very heavy use of the bizarre spam|www.python.org|html>, > and the bizarre feature >""" ... stuff on map files ________________________________ M i k e C . F l e t c h e r mcfletch@golden.net http://www.golden.net/~mcfletch/ ________________________________ Design, Consultation, Training _______________ DOC-SIG - SIG for the Python Documentation Project send messages to: doc-sig@python.org administrivia to: doc-sig-request@python.org _______________ From friedrich@pythonpros.com Mon Feb 23 21:54:54 1998 From: friedrich@pythonpros.com (Robin Friedrich) Date: Mon, 23 Feb 1998 15:54:54 -0600 Subject: [DOC-SIG] Xrefs References: <3.0.2.32.19980223114511.00e0f2b8@pop.golden.net> Message-ID: <34F1F02C.3119F48F@pythonpros.com> I really want to drive this markup to be as unobtrusive as possible to the doc string reader. That's why we chose the footnote style rather than an in-line markup scheme in the first place. If it's at all possible, I prefer the footnote style. Great ideals though. The Xref story so far... gendoc looks for words bounded by [brackets] then adds this text to a dictionary as a key. At the end of the doc string it looks for a line starting with two dots (.. ) and processes that line to determine what that hyperlink refers to. (if there's not a matching label in the footnotes then gendoc just leaves the bracketed text as is.) So it might take the form: .. [O'Reilly] http://www.oreilly.com/catalog/html2/index.html for an ordinary URL, or: .. [Wizbang] win32api:spamDialog.toolBar.wizBangPrime for an external reference object called win32api, or: .. [Geo-model] self.GeoPotentials.Model to point to an object within our current package with an absolute path. Since we mandate full pathing to python objects we don't need to specify what the stating point of the reference is. Note also that the bracket highlighted text does not have to correspond to the object it's pointing to. The Wizbang example is cool in that gendoc could simply make a call to an external object dictionary to ask for the reference information. For example: w32 = get_doc_object_from_picklefile('whatever') ExternalDocs = {'win32api': w32} inserted_href = ExternalDocs['win32api'].get_ref('spamDialog.toolBar.wizBangPrime') to calculate the reference uri. This externalizes the smarts to anyone's own doc network. Boy this crossref stuff can get fun! -- Robin K. Friedrich Houston, Texas Python Professional Services, Inc. friedrich@pythonpros.com http://www.pythonpros.com _______________ DOC-SIG - SIG for the Python Documentation Project send messages to: doc-sig@python.org administrivia to: doc-sig-request@python.org _______________