Mailman 3 February 1998 - Doc-SIG

Re: [DOC-SIG] Xrefs
by Mark Hammond Feb. 23, 1998

Feb. 23, 1998

[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 <namespace-type>[:] <namespace-name> 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 <namespace-type> 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: <reference text|object name|namespace> 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 <win32com client support|win32com.client> It is very similar to the <other sample in othersample.py|win32com.demos.othersample.py|sourcefile>. It makes very heavy use of the bizarre <Python feature spam|www.python.org|html>, and the bizarre feature <eggs that the win32 API provides|eggs|win32api> """ 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(a)python.org administrivia to: doc-sig-request(a)python.org _______________

3 2

RE: [DOC-SIG] Xrefs
by Friedrich, Robin K Feb. 19, 1998

Feb. 19, 1998

>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 <namespace-type>[:] <namespace-name> > >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. ><namespace-type> 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(a)python.org administrivia to: doc-sig-request(a)python.org _______________

3 2

RE: [DOC-SIG] Xrefs (was)Status of documentation effort?
by Friedrich, Robin K Feb. 19, 1998

Feb. 19, 1998

>---------- >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(a)python.org administrivia to: doc-sig-request(a)python.org _______________

2 1

Re: [DOC-SIG] Status of documentation effort?
by Mark Hammond Feb. 19, 1998

Feb. 19, 1998

>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(a)python.org administrivia to: doc-sig-request(a)python.org _______________

2 1

RE: [DOC-SIG] Status of documentation effort?
by Friedrich, Robin K Feb. 18, 1998

Feb. 18, 1998

>---------- >From: Marc Poinot[SMTP:poinot@onera.fr] >Sent: Wednesday, February 18, 1998 4:21 AM >To: doc-sig(a)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(a)python.org administrivia to: doc-sig-request(a)python.org _______________

2 1

RE: [DOC-SIG] Status of documentation effort?
by Friedrich, Robin K Feb. 18, 1998

Feb. 18, 1998

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(a)python.org administrivia to: doc-sig-request(a)python.org _______________

2 1

Status of documentation effort?
by Ken McDonald Feb. 17, 1998

Feb. 17, 1998

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(a)python.org administrivia to: doc-sig-request(a)python.org _______________

2 1