Mailman 3 March 1997 - Doc-SIG

[PYTHON DOC-SIG] Documentation enhancements
by Andrew Kuchling April 1, 1997

April 1, 1997

I've found a publisher who's somewhat interested in producing a printed version of the Python docs, though nothing is certain yet. In the knowledge that there may be a printed version of the 1.5 docs, what changes should be made? Gabriel Berriz made some excellent suggestions, where the priority is improving the index and adding cross-references from module to module. (For example, the rand module would also reference random.py and whrandom.py. Michael K. Johnson at Red Hat independently suggested the same improvement.) Regarding a printed version, what should be in it? Probably the big 4 should all be included: library, reference, extension manual, and tutorial. (Or can the tutorial be left out? I'd vote no, but...) Are there other documents that should be included? Possibilities: * qua.tex * The man page for the Python interpreter * Documentation for the matrix extensions? PIL? Something else? * Is there Windows or Mac documentation that could/should be included? Andrew Kuchling amk(a)magnet.com http://people.magnet.com/%7Eamk/ Save the Gutenberg Project! http://www.promo.net/pg/nl/pgny_nov96.html _______________ DOC-SIG - SIG for the Python Documentation Project send messages to: doc-sig(a)python.org administrivia to: doc-sig-request(a)python.org _______________

5 7

[PYTHON DOC-SIG] Gendoc problem
by viennet＠ura1507.univ-paris13.fr March 28, 1997

March 28, 1997

Hi, Sorry, but I can't get gendoc to work. I always get the error: AttributeError: render_deflist (I use gendoc 0.6, and installed using make install) Any help welcome. Here is the full traceback: % gendoc gendoc_test.py Traceback (innermost last): File "/usr/local/bin/gendoc", line 5, in ? gendoc.gendoc.main() File "/usr/local/lib/python1.4/gendoc/gendoc.py", line 229, in main render_manpages(formats, manpages, head) File "/usr/local/lib/python1.4/gendoc/gendoc.py", line 316, in render_manpages files = render_pages(manpages, formatter) File "/usr/local/lib/python1.4/gendoc/gendoc.py", line 337, in render_pages filename = render_page(page, formatter, prev, next) File "/usr/local/lib/python1.4/gendoc/gendoc.py", line 365, in render_page mantext = manpage.render(formatter) File "/usr/local/lib/python1.4/gendoc/ManualPage.py", line 322, in render apply(self._render_[child[0]], (formatter,)+tuple(child[1:])) File "/usr/local/lib/python1.4/gendoc/ManualPage.py", line 393, in _render_subsection apply(self._render_[child[0]], (formatter,)+tuple(child[1:])) File "/usr/local/lib/python1.4/gendoc/ManualPage.py", line 393, in _render_subsection apply(self._render_[child[0]], (formatter,)+tuple(child[1:])) File "/usr/local/lib/python1.4/gendoc/ManualPage.py", line 450, in _render_deflist formatter.render_deflist(self, list) AttributeError: render_deflist -- Emmanuel Viennet: <viennet(a)ura1507.univ-paris13.fr> LIPN - Institut Galilee - Universite Paris-Nord 93430 Villetaneuse - France _______________ 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] Gendoc
by suir＠nms.otc.com.au March 25, 1997

March 25, 1997

Oops, what I forgot to mention was that I encountered an initial problem with the ni module in gendoc. When I tried to run gendoc the first time, I got the following: Traceback (innermost last): File "./gendoc", line 2, in ? import ni File ".../python/imported/lib/1.4/ni.py", line 435, in ? File ".../python/imported/lib/1.4/ni.py", line 399, in install File ".../python/imported/lib/1.4/ihooks.py", line 364, in install File ".../python/imported/lib/1.4/ni.py", line 390, in install File ".../python/imported/lib/1.4/ni.py", line 239, in init_package File ".../python/imported/lib/1.4/ni.py", line 261, in call_init_module File ".../python/imported/lib/1.4/ni.py", line 204, in load_module File ".../python/imported/lib/1.4/ihooks.py", line 262, in load_module File ".../python/imported/lib/1.4/ihooks.py", line 173, in load_source File "./__init__.py", line 1, in ? path = __.__path__[0] TypeError: unsubscriptable object Any clues as to what's the problem here? Raymond > > > However, I seem to come across the following problem: > > > > *** Importing gendoc > > Collecting information > > Generating documents for HTMLg > > Traceback (innermost last): > > File "./gendoc", line 7, in ? > > gendoc.main() > > ... > > File "./gendoc/formatters/HTMLgenFormatter.py", line 88, in html_rc > > import __ > > ImportError: No module named __ > > > > Does anybody out there know what the "__" module refers to? I tried > looking > > through some python books but found nothing specifically related to this. > > The __ is used by the "ni" module. > > You will probably find you have the "formatters" directory on your path - > it shouldnt be - the "ni" module allows Python to find it in the > sub-directory automatically... > > 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

[PYTHON DOC-SIG] Gendoc
by suir＠nms.otc.com.au March 25, 1997

March 25, 1997

Hello Out There, I have just started playing around with gendoc. I untarred the whole thing and tried running it against a python file. However, I seem to come across the following problem: *** Importing gendoc Collecting information Generating documents for HTMLg Traceback (innermost last): File "./gendoc", line 7, in ? gendoc.main() ... File "./gendoc/formatters/HTMLgenFormatter.py", line 88, in html_rc import __ ImportError: No module named __ Does anybody out there know what the "__" module refers to? I tried looking through some python books but found nothing specifically related to this. Regards, Raymond _______________ 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] Gendoc
by Mark Hammond March 25, 1997

March 25, 1997

> However, I seem to come across the following problem: > > *** Importing gendoc > Collecting information > Generating documents for HTMLg > Traceback (innermost last): > File "./gendoc", line 7, in ? > gendoc.main() > ... > File "./gendoc/formatters/HTMLgenFormatter.py", line 88, in html_rc > import __ > ImportError: No module named __ > > Does anybody out there know what the "__" module refers to? I tried looking > through some python books but found nothing specifically related to this. The __ is used by the "ni" module. You will probably find you have the "formatters" directory on your path - it shouldnt be - the "ni" module allows Python to find it in the sub-directory automatically... 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

[PYTHON DOC-SIG] Bugs in documentation
by tvalusek＠vs.inext.cz March 6, 1997

March 6, 1997

Hi, I'm making a slow progress in reading docs, but I've found some bugs already. General bug: In Library Reference, Chapter 2.1.4 are swapped descriptions of / and % operators. Quite fatal for unexperienced ... HTML downloadable docs: ../icons directory referred in files is not included in .tar.gz package. Tom Valusek _______________ 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

[PYTHON DOC-SIG] _using_ gendoc
by richard.jones＠bom.gov.au March 6, 1997

March 6, 1997

OK, I'm confused. I needed a nicely readable version of the SocketServer documentation, so I thought I'd give gendoc a bash. Well, after getting strange errors (below) in import mode (sorry, I really don't have time to delve into the source), I tried the parsing mode. I got a result, but _none_ of the embedded doc strings made it through... So I tried running gendoc over itself (gendoc.py) and again, no docstrings - either in import mode or in parse mode! Can anyone shed any light on my inability to use gendoc correctly? Please? :) Richard > gendoc -d ../documentation /usr/local/lib/python/SocketServer.py Traceback (innermost last): File "/usr/local/bin/gendoc", line 5, in ? gendoc.gendoc.main() File "/usr/local/lib/python/gendoc/gendoc.py", line 228, in main manpages = collect(args, formats, head) File "/usr/local/lib/python/gendoc/gendoc.py", line 270, in import_collect manpages = doc_collect.gendoc(doc_collect.doc_collect(modules)) File "/usr/local/lib/python/gendoc/doc_collect.py", line 685, in doc_collect return map(collector, module_list) File "/usr/local/lib/python/gendoc/doc_collect.py", line 664, in collector col.collect() File "/usr/local/lib/python/gendoc/doc_collect.py", line 533, in collect elif type(value) == ClassType and \ TypeError: not enough arguments _______________ 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] Templatising gendoc, and more.
by Mark Hammond March 6, 1997

March 6, 1997

> Date: Mon, 3 Mar 1997 11:16:34 -0500 > From: "Barry A. Warsaw" <bwarsaw(a)anthem.cnri.reston.va.us> > To: MHammond(a)skippinet.com.au > Cc: doc-sig(a)python.org > Subject: Re: [PYTHON DOC-SIG] Templatising gendoc, and more. > Reply-to: "Barry A. Warsaw" <bwarsaw(a)CNRI.Reston.Va.US> > > >>>>> "MH" == Mark Hammond <MHammond(a)skippinet.com.au> writes: > > MH> Couple of quick questions - how can a ni package provide doc > MH> strings? Eg, a package named "xyz" is a directory, _not_ a > MH> file. I added a convention to gendoc that a file called > MH> "__doc__" in a packages directory will be read, and treated as > MH> docstrings for the module itself (which makes lots of sense to > MH> me, as then you dont need to distribute it) Also, I "flatten" > MH> the "__init__" module, so that all docstrings and methods are > MH> documented in the package itself - ie, __init__ never gets a > MH> mention in the docs. Do these sound OK? > > I think Ken M. was the first to champion flatting of __init__ into the > package module. The argument is that flattening is the most natural > way to think about package modules and most package authors are going > to want to this, so it makes sense to be the default behavior. I even > went so far as to add the couple of lines to ni.py to make this > happen, but Guido nixed it, partially because there wasn't enough > experience with ni.py to back-up the `most common usage' argument. > > In any case, when I packagized some parts of Grail, I added the > following gross hack (taken from fonts/__init__.py): :-) Ive come up with the same hacks, without ever seeing fonts :-) Ive _always_ done this in __init__, and maybe we would find that the "most common usage" argument is more pervasive now? > What I would to do ni, is automatically put any non-underscore > prefixed symbol appearing in __init__.py into the package module's > namespace. I would also put __doc__ into that namespace. It's all of > a two or three line change to ni.py. Also, you might provide some way > of controlling what gets put into the package's namespace from > __init__.py. Im sure many people will dis-agree here, but IMO docstrings in the code is cute, but on-line browsing of docstrings wont be used anywhere near as much as generated documentation. I think it most important docstrings be kept near the sources for maintenance, rather than browsing. I'd ask if flattening of the doc strings at run-time is really worth it? Another interesting "feature" of docstrings is that the sources often get _twice_ as big (Python is partly to blame here, as the programs themselves are often so small :-). If you consider the win32com stuff, not only are the sources twice as big, all the doc strings are _also_ in the generated HTML. And at run-time, obviously, they take more memory. And the more keen you are with the documentation, the more penalty you pay. (OK - were not talking too much, and Im not really _that_ concerned, but...) This is one reason why I like my new little __doc__ file convention. It means I can put "overview" type information in a seperate file that is included in the HTML build, but not part of the sources (but still very close). Browsers wont see it, but people browsing wont be looking for "overview" information anyway - they are more likely to be looking for a specific object... 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 _______________

3 2

[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] Needed Python docs in RTF format
by tvalusek＠vs.inext.cz March 3, 1997

March 3, 1997

Have you checked out all the Win95 options for this sort of thing? You may find you can adjust winhelp to a more suitable size. However, I admit to not knowing much about these options. Of course I use the maximum available font size in WinHelp, but WinHelp version is rather buggy, because some articles are not accesible from "contents" tab (they appear there as books) and accesed via "Index" WinHelp pops up window saying something about wrong window name (but after hitting OK the text appears). Another problem is that I hate WinHelp's behaviour to print each topic on separate page. I also cannot affect the font size on written output. What about grabbing the .HTML versions, and either configuring your browser of choice to use the big fonts? Thats the easiest I can come up with. Do you know about FREE (non-shareware) Web site grabber? There are some available comercially, but they are rather expensive for me. Tom Valusek _______________ 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