Mailman 3 February 1997 - Doc-SIG

[PYTHON DOC-SIG] Templatising gendoc, and more.
by Mark Hammond March 3, 1997

March 3, 1997

Couple of quick questions - how can a ni package provide doc strings? Eg, a package named "xyz" is a directory, _not_ a file. I added a convention to gendoc that a file called "__doc__" in a packages directory will be read, and treated as docstrings for the module itself (which makes lots of sense to me, as then you dont need to distribute it) Also, I "flatten" the "__init__" module, so that all docstrings and methods are documented in the package itself - ie, __init__ never gets a mention in the docs. Do these sound OK? Secondly - by default, there are a few places it is assumed the file name of the generated file is the same as the object itself. Thus, the module "a.b" is created as "a.b.html". Is it worth making a change to that it is created as "a_b.html"? Up until recently, even Python could not correctly parse the extension from a.b.html, so Im inclined to think it is. 2 ways to tackle this - unconditionally replace "." with "_" in object names, or allow the classes to have the concept of _2_ names - the objects name, and the generated file name. The latter is more general, but touches more code... Now, the main one. This may sound a little wierd and hard, but here goes anyway... Something I didnt really like about gendoc was the way it enforced a "synopsis"/"description"/"See also" type format on your documentation. As I read about the StructuredText module that Jim did, what I really expected what that _my_ structure would be used for the documentation. Eg, what I expected to be able to write was: """Some Module: Description This is the desc Known Bugs Lots and lots See Also Some extra stuff Synopsis At the bottom! :-) """ and I expected that my "See Also" stuff would automatically go into the "See Also" section on the Web page, and that a top-level "Known Bugs" section would appear in the HTML - it doesnt :-( I have a few ideas on how you could do this. My idea is basically to have 2 modes - a "template" mode, and a "freeform" mode. The (default?) "template" mode is much like now, but would use a text file of "known" section names. Eg, the "default" template, which would generate doc identical to now would be like: Synopsis|<H2>%s</H2>|<P> Description See Also [The stuff after the | could be optional, and defines how the heading itself it rendered, and also how para in the body is pre/a-pended. Thats off the top of my head - consider the concept, not my impl idea :-) And someone else could change it if required for their documentation needs. Free-form mode would still use "known" section names, but would use the top-level structure of the structured doc-string to determine the order and inclusion of sections. Eg, in the example above, the "generated" see also entries (as now) would be appended/prepended to the "explicit" see also entries (which the module author specifies as relevant, but gendoc didnt), and no "synopsis" section at all would be generated (which may make sense for sample modules, for example, where an implication of importing the sample code is not correct) Any comments on this? Mark. ---------------------------------------------------------------------- Mark Hammond - MHammond(a)skippinet.com.au Check out Python - _the_ language for the Web/CGI/Windows/MFC/Unix/etc <http://www.python.org> & <http://www.python.org/ftp/python/pythonwin> _______________ 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] New ni style example.
by Mark Hammond March 1, 1997

March 1, 1997

> Ahh well... IMHO The indentation is far too wide.. Im glad we all agree here. In this particular case, one obvious problem is that _all_ objects are shown in the index. IMO, it would be vastly improved if only modules and sub-modules were included in the index. Unfortunately, the index generater has long ago lost what the original objects are - it only has the man-pages and filenames. This would be a reasonable change, to have the index generator work from the collectors too. And another Microsoft-centric rant, which I'd like to pass by you all. Microsoft is moving its entire help system to HTML!!! It is doing this in 2 ways: * By adding special keyword and indexing tags to the HTML standard, and submitting them for approval. Apparently, the relevant body modified it, renamed it, and ratified it. * By designing yet another something-or-other which allows many HTML files to be concatenated into some sort of container, including I think compression. They will then submit this to whoever does this stuff. The special tags for indexing and keywords are something I would find particularly useful - (even necessary) - the C based .HLP generator I have still produces far far superior documentation than HTMLgen - and largely for these reasons. Is anyone else interested in this? I definately wont find the time to look at this on my own, and Id really like to get gendoc where it makes really really good documentation - I fear my new optimism for all this stuff will wane... Mark. ---------------------------------------------------------------------- Mark Hammond - MHammond(a)skippinet.com.au Check out Python - _the_ language for the Web/CGI/Windows/MFC/Unix/etc <http://www.python.org> & <http://www.python.org/ftp/python/pythonwin> _______________ 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] New ni style example.
by Mark Hammond Feb. 28, 1997

Feb. 28, 1997

> |<()()|_N|=SS :-) Looks quite good.. but.. it would be nice to have > some kind of folding mechanism *SLAP* oh yeah this is html.. (humm > maybe some coffe would do fine, java or javascript that can fold/unfold > lists?) Well, Im more likely to generate Python ActiveX Scripting code - only Explorer, tho, but I dont care :-) [Then I could even display the HTML in Pythonwin, too :-] Mark. ---------------------------------------------------------------------- Mark Hammond - MHammond(a)skippinet.com.au Check out Python - _the_ language for the Web/CGI/Windows/MFC/Unix/etc <http://www.python.org> & <http://www.python.org/ftp/python/pythonwin> _______________ 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

Re: [PYTHON DOC-SIG] New ni style example.
by Andy Eskilsson Feb. 27, 1997

Feb. 27, 1997

/ Mark Hammond <MHammond(a)skippinet.com.au> wrote: | | Please let me know what you think... | | http://www.labyrinth.net.au/~mhammond/win32com/ | |<()()|_N|=SS :-) Looks quite good.. but.. it would be nice to have some kind of folding mechanism *SLAP* oh yeah this is html.. (humm maybe some coffe would do fine, java or javascript that can fold/unfold lists?) Ahh well... IMHO The indentation is far too wide.. /Andy _______________ 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] New ni style example.
by Mark Hammond Feb. 27, 1997

Feb. 27, 1997

All the hacks I have done have resulted in documentation for the win32com module. Ive uploaded the html, for anyone to peruse if they are interested. Key things to note: * Entire manual generated by telling gendoc to document the "win32com" package, and specifying some "skip-modules". All sub-modules were found and documented automaticaly. * Index is still ugly, no frames, and too wide * References can appear in the body text. * More module names are written as links, rather than text. * Added the "one-liner" to a few more places. Please let me know what you think... http://www.labyrinth.net.au/~mhammond/win32com/ Mark. ---------------------------------------------------------------------- Mark Hammond - MHammond(a)skippinet.com.au Check out Python - _the_ language for the Web/CGI/Windows/MFC/Unix/etc <http://www.python.org> & <http://www.python.org/ftp/python/pythonwin> _______________ 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] Hacking relentlessly :-)
by Mark Hammond Feb. 19, 1997

Feb. 19, 1997

Ive added cross-references in the text. I dont know what syntax to use. My current hacks allow docstrings such as: "See also @a.b.c@", and "a.b.c" will be translated into a hyperlink if such an object has been collected in this run, else into Bold. What syntax should I use for this? I thought of a regex that dectected _any_ "a.b.c", but in some cases, the link will be a single word - ie, no "." sep'd. Also, I noticed that manpage.py did _not_ process markups or internal hyperlinks for list definitions, etc - only paragraphs. Is there a reason for this? Having markups and links in definition lists seems pretty logical to me... Mark. ---------------------------------------------------------------------- Mark Hammond - MHammond(a)skippinet.com.au Check out Python - _the_ language for the Web/CGI/Windows/MFC/Unix/etc <http://www.python.org> & <http://www.python.org/ftp/python/pythonwin> _______________ 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

Re: [PYTHON DOC-SIG] Hacking relentlessly :-)
by Daniel Larsson Feb. 19, 1997

Feb. 19, 1997

Mark Hammond wrote: > > [You dropped the SIG - was that intentional?] Nope! I resent my message to the group. > > > Why did you decide to skip the link if it wasn't collected? Presumably > > to > > avoid having dead links, but that also means you have to "collect" > > possibly > > a lot of files in one run. > > Yup - this was the idea. These links are "internal" by definition. > If they cant be found in the current build, they wont be found later > :-) Ok. I sometimes used links to standard classes, but then gendoc assumed the resulting HTML files would reside in the same directory. > Note that _no_ URL is entered. The whole point of these markups is > for the generater to _deduce_ the URL name, based on the object name. Yes, I understand that. That's what I did as well. > IMHO, it should be possible to create a single package with gendoc > that has _zero_ bad links. This currently is pretty hard :-) Hmm, true. I insert all kinds of links, such as when you import modules, inherit from classes, etc. Maybe add YAO (yet another option) to avoid generating links to things we're not sure are there (or perhaps the other way around, an option to generate links regardless if they are seen during this collect). > > While on the gendoc thread: I usually run gendoc on everything in the > > standard distribution to put up docs for people in my department. I > > thought of adding > > an option to "collect" every module (and package) along the sys.path. > > Comments? > > Makes sense to me. This is what I do for ni(), so I suppose it is > pretty similar. > > I also added a "-s" option to gendoc, so the skiplist can be added > to. > -- Daniel Larsson, ABB Industrial Systems AB

1 0

Re: [PYTHON DOC-SIG] Hacking relentlessly :-)
by Daniel Larsson Feb. 19, 1997

Feb. 19, 1997

Mark Hammond wrote: > > Ive added cross-references in the text. I dont know what syntax to > use. My current hacks allow docstrings such as: > "See also @a.b.c@", and "a.b.c" will be translated into a hyperlink > if such an object has been collected in this run, else into Bold. > > What syntax should I use for this? I thought of a regex that > dectected _any_ "a.b.c", but in some cases, the link will be a single > word - ie, no "." sep'd. Originally, I had a syntax for doing this, but I removed it. I always made the link, however, regardless of whether the source was collected or not. Why did you decide to skip the link if it wasn't collected? Presumably to avoid having dead links, but that also means you have to "collect" possibly a lot of files in one run. > Also, I noticed that manpage.py did _not_ process markups or internal > hyperlinks for list definitions, etc - only paragraphs. Is there a > reason for this? Having markups and links in definition lists seems > pretty logical to me... Ooops, yes of course that's logical. Stupid darn mistake of mine. While on the gendoc thread: I usually run gendoc on everything in the standard distribution to put up docs for people in my department. I thought of adding an option to "collect" every module (and package) along the sys.path. Comments? -- Daniel Larsson, ABB Industrial Systems AB

1 0

Re: [PYTHON DOC-SIG] Observations about gendoc.
by Mark Hammond Feb. 16, 1997

Feb. 16, 1997

> Thats all for today! > Is that today or yesterday, and if so what are you doing > tomorrow... oh forget it. Hey - its tomorrow today! And today, Im hacking even more relentlessly... Ive decided my previous "ni" hacks are inappropriate. My strategy now is: * In gendoc.py, wrote a new collector called "ni_collect()". This does a file system search of sub-modules, and imports them all! (honouring the skiplist, etc) * doc_collect has a new collector called "PackageCollector" - currently sub-classes from ModuleCollector, but should probably be rolled into it. * Changed some of the generate stuff to be recursive. Thus, the list of manpages is now a list of [manpage|list of manpages], etc. All this leads to a nice heriarchical index of the entire package. So my questions: * Does this sound reasonable? The recursive changes mean that it still works as before. This _seems_ the correct design for ni, which is recursive by nature. This could possibly be put to good use elsewhere. * Re the index. How should I generate it? With no frame, an indented list seems right. But if I have frames, an indented list will be too "wide". Best thing that comes to mind is some sort of nested set of index pages or something...Maybe dont use an actual HTML list (eg, heading levels) , to keep the width down. How about generating for an MSIE tree control :-):-) Any advice on this? Mark. ---------------------------------------------------------------------- Mark Hammond - MHammond(a)skippinet.com.au Check out Python - _the_ language for the Web/CGI/Windows/MFC/Unix/etc <http://www.python.org> & <http://www.python.org/ftp/python/pythonwin> _______________ 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] Observations about gendoc.
by Robin.K.Friedrich＠USAHQ.UnitedSpaceAlliance.com Feb. 14, 1997

Feb. 14, 1997

______________________________ Reply Separator _________________________________ Subject: [PYTHON DOC-SIG] Observations about gendoc. Author: Mark Hammond <MHammond(a)skippinet.com.au> at INTERNET Date: 2/14/97 3:14 AM Reply: Robin Friedrich Im starting to look into some of those changes I mentioned before. On my way Ive noticed a few things... All comments appreciated. I'll take a lack of objections as implicit approval to hack these changes, and submit them back :-) * .htp files. Is Ken on this list? www.python.org wants .htp files, which a script then converts to html. Whats the best way to tackle this? Just setup a "template" to make it look like the finished .html, and skip the conversion process? I'm not sure .htp file format is important enough to provide a separate plugin. The things gendoc is used for is not likely to wind up as integrated python.org pages. It would be easier to provide an HTMLgen resource class that matches the python.org style. * Exceptions - It looks like much of this code pre-dates a useful traceback module. Some handlers print sys.exc_type, sys.exc_value etc (syntax error handling comes to mind) - should these be upgraded to print the full traceback? * Private Methods - I would find it useful if there was a mode which says "use Private Methods, but only if they have a docstring. ie, the existance of a docstring dictates its private-ness. In fact, maybe a more general "only export is docstring'd" flag - regardless of the leading "_". Personally, I prefer the first option better... Good one. I like the first option as well. Although what we do is run gendoc for two purposes -- one is user docs, but the other is detailed docs that we slap into our DDS (detailed design specifications). We thus need to retain the current capability as well. Thats all for today! Is that today or yesterday, and if so what are you doing tomorrow... oh forget it. -Robin 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 _______________

1 0