Mailman 3 January 2000 - Doc-SIG

Docstring grammar: a very revised proposal
by David Ascher Feb. 7, 2000

Feb. 7, 2000

Over the last week, I've been incorporating all of the comments that various folks made in the DOC-SIG about the docstring grammar proposal, and writing code to provide a reference implementation. It's been going well, and I was polishing up to post it. In preparation of a discussion at IPC8's DevDay, and anticipating (perhaps mistakenly) some resistance to "yet another structured text format" from Jim Fulton, I went to look at StructuredText to find out what aspects of it I had problems with in the past. Just as a point of historical interest, I have long been a fan of the idea behind StructuredText, and have used a fairly old version of it to generate much of my website automatically. I stopped doing so because I found it lacking for the things I was trying to get it to do, unintuitive at times, and too hard to modify for my (somewhat exotic) needs. I just looked again at StructuredText's rules (not code) within the context of "Python code documentation" exclusively (a much more narrow domain than website management), and found it better-suited than I remembered, with three kinds of problems: - StructuredText is too generic -- in markup terms, it's much like SGML or XML without a DTD (or with a very weak one). So while it's an OK markup, it's too weak as it stands. - StructuredText has some markup rules which I think are wrong, in the sense that they fail the "naturalness" test which we set out to use in our alternative markup or they cause "bad" side-effects when a docstring is not fully marked up. - Missing features (not surprising -- the aim is different) I'll describe each of the kinds of problems in detail, but first, let's look at the rules which are followed by the *latest* version of StructuredText.py, which is available at the Zope CVS site. I include the docstring for StructuredText.py here: Structured Text Manipulation Parse a structured text string into a form that can be used with structured formats, like html. Structured text is text that uses indentation and simple symbology to indicate the structure of a document. A structured string consists of a sequence of paragraphs separated by one or more blank lines. Each paragraph has a level which is defined as the minimum indentation of the paragraph. A paragraph is a sub-paragraph of another paragraph if the other paragraph is the last preceding paragraph that has a lower level. Special symbology is used to indicate special constructs: - A single-line paragraph whose immediately succeeding paragraphs are lower level is treated as a header. - A paragraph that begins with a '-', '*', or 'o' is treated as an unordered list (bullet) element. - A paragraph that begins with a sequence of digits followed by a white-space character is treated as an ordered list element. - A paragraph that begins with a sequence of sequences, where each sequence is a sequence of digits or a sequence of letters followed by a period, is treated as an ordered list element. - A paragraph with a first line that contains some text, followed by some white-space and '--' is treated as a descriptive list element. The leading text is treated as the element title. - Sub-paragraphs of a paragraph that ends in the word 'example' or the word 'examples', or '::' is treated as example code and is output as is. - Text enclosed single quotes (with white-space to the left of the first quote and whitespace or puctuation to the right of the second quote) is treated as example code. - Text surrounded by '*' characters (with white-space to the left of the first '*' and whitespace or puctuation to the right of the second '*') is emphasized. - Text surrounded by '**' characters (with white-space to the left of the first '**' and whitespace or puctuation to the right of the second '**') is made strong. - Text surrounded by '_' underscore characters (with whitespace to the left and whitespace or punctuation to the right) is made underlined. - Text encloded by double quotes followed by a colon, a URL, and concluded by punctuation plus white space, *or* just white space, is treated as a hyper link. For example: "Zope":http://www.zope.org/ is ... Is interpreted as '<a href="http://www.zope.org/">Zope</a> is ....' Note: This works for relative as well as absolute URLs. - Text enclosed by double quotes followed by a comma, one or more spaces, an absolute URL and concluded by punctuation plus white space, or just white space, is treated as a hyper link. For example: "mail me", mailto:amos@digicool.com. Is interpreted as '<a href="mailto:amos@digicool.com">mail me</a>.' - Text enclosed in brackets which consists only of letters, digits, underscores and dashes is treated as hyper links within the document. For example: As demonstrated by Smith [12] this technique is quite effective. Is interpreted as '... by Smith <a href="#12">[12]</a> this ...'. Together with the next rule this allows easy coding of references or end notes. - Text enclosed in brackets which is preceded by the start of a line, two periods and a space is treated as a named link. For example: .. [12] "Effective Techniques" Smith, Joe ... Is interpreted as '<a name="12">[12]</a> "Effective Techniques" ...'. Together with the previous rule this allows easy coding of references or end notes. - A paragraph that has blocks of text enclosed in '||' is treated as a table. The text blocks correspond to table cells and table rows are denoted by newlines. By default the cells are center aligned. A cell can span more than one column by preceding a block of text with an equivalent number of cell separators '||'. Newlines and '|' cannot be a part of the cell text. For example: |||| **Ingredients** || || *Name* || *Amount* || ||Spam||10|| ||Eggs||3|| is interpreted as:: <TABLE BORDER=1 CELLPADDING=2> <TR> <TD ALIGN=CENTER COLSPAN=2> <strong>Ingredients</strong> </TD> </TR> <TR> <TD ALIGN=CENTER COLSPAN=1> <em>Name</em> </TD> <TD ALIGN=CENTER COLSPAN=1> <em>Amount</em> </TD> </TR> <TR> <TD ALIGN=CENTER COLSPAN=1>Spam</TD> <TD ALIGN=CENTER COLSPAN=1>10</TD> </TR> <TR> <TD ALIGN=CENTER COLSPAN=1>Eggs</TD> <TD ALIGN=CENTER COLSPAN=1>3</TD> </TR> </TABLE> ------- This markup has nice features: - it's very similar to the core of what we were discussing (no big surprise, since my proposal was mostly stolen from earlier StructuredText =). - The (new to me) mechanism for dealing with references to URLs and to other bits of text is quite elegant. Ok, now onto the problems with the above markup rules, IMO of course. StructuredText as XML without a DTD: Unlike the grammar which was discussed on the doc-sig, StructuredText does not allow us to specify special syntax for special kinds of text, such as: signature blocks/tooltip descriptions, doctest.py code, and keyworded paragraphs. This is a lack of feature rather than a flaw, and could maybe be fixed by adding a postprocessor which would be Python-internal-doc specific. StructuredText as a markup with some flaws for inline doc: The use of single quotes to markup inline code (as in 'x') can be surprising. Many current docstrings use 'x' to refer to the *string* containing the character x, not the variable x. In StructuredText, the quotes would dissappear in the rendering. With practice, the current scheme could be used but users would have to learn to write '"x"' to have their intent carry through to the renderer. This is probably my biggest problem with StructuredText because I don't know how to fix it while maintaining compatibility. Related questions for Jim or Ken are 1) How does StructuredText parse ''? 2) How can one have a single quote in verbatim text? The tagging of underlined text with _'s is suboptimal. Underlines shouldn't be used from a typographic perspective (underlines were designed to be used in manuscripts to communicate to the typesetter that the text should be italicized -- no well-typeset book ever uses underlines), and conflict with double-underscored Python variable names (__init__ and the like), which would get truncated and underlined when that effect is not desired. Note that while *complete* markup would prevent that truncation ('__init__'), I think of docstring markups much like I think of type annotations -- they should be optional and above all do no harm. In this case the underline markup does harm. The requirement that a paragraph end with the word example or examples or :: goes against my natural style, as I often do not want such word or punctuation before a "displayed" paragraph. Furthermore, the spec currently doesn't say how the renderer is supposed to process the :: -- is it displayed as two colons, one, or none? If the two colons are not displayed by the renderer, then my objection is diminished, although I would have preferred a markup which is local to the paragraph which is affected, not the previous one (cut and paste errors follow too easily). In some versions in the past at least, both colons were displayed. I'll leave that as an open question, as additional markup could provide an alternative which would suit me. Missing features: The definition of references is well-designed for referencing URLs. The docstring proposal needs to address referencing other code elements (methods of current class, other classes, other methods of other classes, builtin modules, imported modules, etc.) This is also more of a lack of feature than a real flaw, and defining the namespaces for lookup of 'reference targets' would probably go most of the way towards fixing the spec for our needs. The DOC-SIG folks strongly wanted to be able to have list items not require blank lines in between them. This is not hard to do from scratch (I've got code to do it). I suspect it could be added to StructuredText as a postprocessing step. (From experience, such list items should be required to be indented relative to the previous line, to avoid spurious bulletization.) I think many folks liked the idea of "tagged" paragraphs, as in: Author: Guido van Rossum and Release-History: 0.1: June 1920 0.2: July 1919 etc. Again, postprocessing smarts for this could be added while keeping backwards compatibility. Many of the features related to these tagged paragraphs (internationalization of keywords, etc.) could be dealt within the postprocessor. Technical points: StructuredText.py uses the regex module, which is deprecated. StructuredText.py currently rarely produces an exception. The output may not be what you expected, but it will produce output. For a rigorous docstring markup, I'd expect to see much stricter rules enforced, which raises technical questions (the line numbers for example are not maintained as part of the StructuredText.py parsing process I suspect). This requirement would probably have the most impact on the current source. Assuming this analysis is correct, I am inclined to scrap my original proposal, shelve my current prototype code, and work instead with Jim Fulton and whoever else to discuss whether and how to modify StructuredText's format and code to extend it to the needs which the DOC-SIG expressed. The value in this approach is: - StructuredText.py (the code) exists and works. (prior art) - There is a fair bit of code which uses StructuredText's markup. (user base) - Much of the work would be postprocessing of StructuredText.py analysis. (modularity) - The features of the current markup which are deemed problematic could be disabled with a runtime switch if the StructuredText community disagrees with my assessment. (configurability) An alternative course of action is to take StructuredText.py and modify and rename it (aka code fork) This is of course less desirable, but would be the efficient way of dealing with either irreconciliable differences of opinion or differing needs (It is possible that the Zope folks do not want to see their code burdened with e.g. line number maintenance code because of performance or other reasons). We also need to know whether the Zope folks would *want* to push StructuredText.py into the Python standard library, which I have always assumed to be a goal for whatever tool we come up with. A final alternative is for me to revise my current (unpublished) manuscript to incorporate some of the things I like about StructuredText which we didn't have (the reference naming scheme mostly), and keep a parallel track in spec and code. Just as a point of note: I do maintain that keeping StructuredText as it currently is without postprocessing is inadequate for intelligent docstring markup, and do not consider that a solution to the problem at hand, although it's a fine everyday strategy in the absence of a solution. I would like to discuss which approach should be followed at the DevDay session. Feel free to email or post feedback between now and the conference, whether or not you'll be there. Assuming a discussion does take place, I'll try to post a summary post-conference. Cheers, David Ascher

3 3

RE: Doc-SIG digest, Vol 1 #134 - 1 msg
by Ken Manheimer Jan. 31, 2000

Jan. 31, 2000

> Date: Fri, 28 Jan 2000 08:16:06 +0200 (IST) > From: Moshe Zadka <moshez(a)math.huji.ac.il> > Reply-To: Moshe Zadka <mzadka(a)geocities.com> > To: doc-sig(a)python.org > Subject: [Doc-SIG] Some Premilinary Thoughts on Syntax > > [...] > The first thing we would need is to make sure the two markups are > semantically equivalent. More precisely, we'll need to figrue out what > "element" (to use XML terminilogy) an embedded doc string corresponds to > in the OOL (out of line) documentation, and make sure we have a one to one > correspondence betweent the syntaxes. At the risk of being flamed to > death, I will offer that this means throwing StructureText clean out of > the door, as it is impossible to reason about it. The only structured text > idea that would be left would be indentation for blocks, because it > meashes well with the rest of the code. No flames here, i'm only for going with StructuredText if it suits the purpose. But i don't understand your disqualifying criterion. Specifically, i don't see *why* there must be a one-to-one correspondence between the OOL and docstring documentation. I would think the requirement is that all docstring elements map to some OOL elements, but that it's acceptable - probably even desirable - for the collection of docstring elements to be a subset of the OOL collection. Ie, seems to me that there's a lot of stuff that the OOL needs that the docstrings emphatically don't - i'd assume docstrings are pretty localized elements that may need to refer to, but don't need to embody, the larger-scale (chapters, sections, etc) or more specialized (footnotes, tables-of-contents, etc) book structures. If so, i don't see why the StructuredText approach would be disqualified at the outset (colloquialism for "at the start"). And in fact it seems to me that something like StructuredText is necessary to satisfy readability/naturalness, if those are in fact requirements. Ken Manheimer klm(a)digicool.com

2 1

Monty: A structured text syntax idea
by Sean Mc Grath Jan. 31, 2000

Jan. 31, 2000

""" idea: para: I was editing some text in Python emacs mode the other day. para: I got to thinking how Python mandatory indentation emph: removes much of the need for delimiters para: Then it occured to me that XML tags are basically delimiters of nested block structures. para: Before I new it, I had written this structured text document, trivially parseable, trivially convertable to XML or whatever and christened it bold: Monty in honour of Python from which the idea came. para: I have started using this format in my docstrings and find Barry's amazing Python editing mode to be a very pleasent - um - structured text authoring tool! """ http://www.pyxie.org - an Open Source XML Processing library for Python

5 4

Some Premilinary Thoughts on Syntax
by Moshe Zadka Jan. 28, 2000

Jan. 28, 2000

Since I won't be back at home until next week, and since the DOC-SIG devday sort of nominated me to suggest a syntax for the documentations, I'll just outline what I think is needed, how I plan on feeling that need, and skectch the specs and software needed. There was a consensus that there should be two syntaxes -- one for the embedded doc-strings, and one for out-of-line documentation. (Note that wherever I refere to doc strings from now on, a doc string is the concatanation of all initialstrings in ..., as opposed to the python interpreter. This is deliberate, and is meant to hve doc strings which can be optimized away). The first thing we would need is to make sure the two markups are semantically equivalent. More precisely, we'll need to figrue out what "element" (to use XML terminilogy) an embedded doc string corresponds to in the OOL (out of line) documentation, and make sure we have a one to one correspondence betweent the syntaxes. At the risk of being flamed to death, I will offer that this means throwing StructureText clean out of the door, as it is impossible to reason about it. The only structured text idea that would be left would be indentation for blocks, because it meashes well with the rest of the code. Then we need a spec to define how an ool document can refer to the documentation inside a module. I'm thinking of a template mechanism, since it generalizes the two common cases -- - complete ool documentation would be a paramteter-less template - complete embedded documentation would be using the default template. The requirement for both of the syntaxes are that they would be very human writable, and yet structurally equivalent to XML. The ool is relatively easy -- we'll use XML plus some of the minimization from XML. Paul Prescod seemed to say something about it in the elevator, and I'm hoping to beat something more concrete out of him. The embedded is up for grabs -- I'm not yet cnvinced it should be human (as opposed to doc-writer) readable, since I think >> import help >> help.help(foobar) is infinitely better then >> print foobar.__doc__ And if it's not, we should be able to use hooks in the interpreter to convert the doc-sig to readable text before it ends up in foobar.__doc__. Disclaimer: These are late-night thoughts more written as notes to myself. I'm not as convinced about things as I sound, so if you have some diagreement, please mail me (personally, prefereably, to forestall the inevitable flamewar) -- Moshe Zadka <mzadka(a)geocities.com>. INTERNET: Learn what you know. Share what you don't.

1 0

Re: lib reference in Unix man format
by Gerrit Holl Jan. 27, 2000

Jan. 27, 2000

Hello, Tao Lu wrote on 948966533 in comp.lang.python: > Where can I find the lib reference in Unix man format? Forgive me if this has > been asked before. > > Have been programming in Perl for years, I found those perlfunc/perlop/perlfaq > are very convenient. Any similar work done for Python developers/newbies? This doesn't exist, does it? I think many people would like it if it would be done; the documentation and the howto's are available in quite a lot formats; why not add another one? regards, Gerrit. -- Please correct any bad English you encounter in my email message! -----BEGIN GEEK CODE BLOCK----- http://www.geekcode.com Version: 3.12 GCS dpu s-:-- a14 C++++>$ UL++ P--- L+++ E--- W++ N o? K? w--- !O !M !V PS+ PE? Y? PGP-- t- 5? X? R- tv- b+(++) DI D+ G++ !e !r !y -----END GEEK CODE BLOCK-----

1 0

docstring grammar
by David Ascher Jan. 27, 2000

Jan. 27, 2000

Proposed format for docstrings: The whitespace at the beginning of a docstring is ignored. Paragraphs are separated by one or more blank lines. For compatibility with Guido, IDLE and Pythonwin (and increasing the likelihood that the proposal will be accepted by GvR), the docstrings of callables must follow the following convention established in Python's builtins: >>> print len.__doc__ len(object) -> integer Return the number of items of a sequence or mapping. In other words, the first paragraph must fit on a line, repeat the name of the callable, with a 'wordy' signature, the ' -> ' string, and the type of the return value. The second paragraph must be a one-sentence description of the callable. It is also allowed to have those two bits separated by a " -- " string: >>> print [].pop.__doc__ L.pop([index]) -> item -- remove and return item at index (default last) and functions which don't return anything can omit the " -> foo" bit: L.append(object) -- append object to end Each paragraph is either 'text' or a 'keyword-tagged block'. A keyword is a case-sensitive element of [a-zA-Z_]+ followed by two colons (with optional whitespace between the keyword and the colons, but no whitespace allowed between the two colons). A paragraph which doesn't start with a keyword is 'text'. Characters between # signs and the end of the line are stripped by the docstring parser. A 'keyword-tagged block' is nested much like Python code. Just like in Python, the block can either be on the same line as the keyword if it is one-line long (I'll refer to such blocks as 'text' blocks even though they aren't in visual paragraphs), or needs to be indented relative to the keyword. Examples: Author:: Guido van Rossum # comments are stripped Date_of_release :: 1/1/1999 # The key is "Date_of_release" and the # whitespace before the : is stripped Contributors:: # The value is a block of lines. John Doe Ronald Reagan Francois Mitterand Some keywords can have special parsing rules, as the block of text which the keyword designates is well-specified by the rules above. The first example of such a keyword-specific parsing rule is for Arguments: Arguments:: self -- instance input (sequence) -- the sequence which is being processed (the specific syntax of Arguments:: is left for a later discussion). Other candidates which can impose specific parsing rules are: ReturnType, Date, Version, etc. Text blocks can be followed by indented blocks as well -- those are 'children' blocks of the outdented block. 'text' blocks which start with * or - are tagged as 'bullet items' for rendering. The bullet marker has to be consistent within a given level of indentation. Example: * this is one bullet - this is a sub-bullet - this is another sub-bullet * this is another bullet In text blocks, some strings are recognized as links: .foo in the docstring of a class will refer to the foo attribute of the class. In the docstring of a method, it will refer to the foo attribute of the method's class. In the docstring of a module it will refer to a function or class defined in that module foo.bar will refer to the bar attribute of foo, which will be looked up in the following namespaces in order: (to be determined) URL notation is automatically recognized. [foo] refers to the keyword 'foo' in the section 'References' of the current docstring. [..] links cannot span multiple lines or contain whitespaces (as keywords can't). (in other words, if a [ is not matched by a ] in the same line or before a whitespace character is hit, then it is a syntax error. References:: foo:: My Dissertation, University Press, 1902 The set of keywords which are 'officially sanctioned' is: For module docstrings: [see Trove discussion for a good starting set -- this discussion has been had!] For class docstrings: [To be determined] For method docstrings: [To be determined] For function docstrings: [To be determined] Miscellaneous Thoughts: I chose double-colon notation for keywords so that one can have text paragraphs which match the 'word:' notation without having them be interpreted as keywords. Does this proposal make docstrings whitespace-heavy -- the requirement to break each paragraph with a line of whitespace means that a lot of lines are blank, especially when doing 'bulleted lists' The above was (quickly) written with parsing in mind. Is it really easily parseable? If not, what needs to be changed so that it is parseable? I also wanted to make sure that syntax errors could be flagged early and 'localized' for aid in debugging. I'm not sure that I did that carefully enough. Are there normal uses in docstrings where one wants to turn off the automatic link detection? Is there value in having string interpolation? David Arnold mentioned __version__ = "$Revision$[11:-2] __date__ = "$Date$ which raises some issues. I don't think that having [11:-2] evaluated by the docstring parser is a wise idea. However, I can imagine that the module author could do: __version__ = "$Revision$"[11:-2] in the Python code, and then Version:: %(__version__)s in the docstring and that such a simple string interpolation mechanism could have value. I'm not sure it's worth the complication though. What dictionary would be used to do the interpolation? Hopefully constructively, --david PS: It goes without saying that while I railed against design by committee, I am of course hopeful for feedback, for technical reasons (dummy, you forgot special cases X, Y and Z!) and because I realize that a standards proposal needs at least broad agreement if not consensus to be effective in the long run. The sharper-eyed will note that I stacked the deck in my favor in the above proposal by including what Guido does naturally as valid in the proposed grammar.

14 79

RE: Docstring grammar: a very revised proposal
by Ken Manheimer Jan. 25, 2000

Jan. 25, 2000

David Ascher wrote: > Assuming this analysis is correct, I am inclined to scrap my original > proposal, shelve my current prototype code, and work instead with Jim Fulton > and whoever else to discuss whether and how to modify StructuredText's format > and code to extend it to the needs which the DOC-SIG expressed. The value > in this approach is: Cool! David, we would be glad to have this happen. We like StructuredText, and would love to see it widely used and available. And we have very limited time right now, which means we would be very happy to have someone like you/the python community making harmonious changes. I think jim and/or i could field your questions/suggestions, to try to keep us in agreement. Re the specifics in your message: > StructuredText as XML without a DTD: > > Unlike the grammar which was discussed on the doc-sig, StructuredText > does not allow us to specify special syntax for special kinds of text, > such as: signature blocks/tooltip descriptions, doctest.py code, > and keyworded paragraphs. This is a lack of feature rather than a flaw, > and could maybe be fixed by adding a postprocessor which would be > Python-internal-doc specific. I'm not entirely clear about what you're referring to, but we're thinking about a slightly different structure for the StructuredText object that may admit this sort of thing. A base class would just be responsible for parsing paragraphs (including distinguishing bullet paragraphs that aren't newline separated - yay!), then a document-formatting class, maybe abstract, that recognizes generic document features like headers, emphasis, links, etc. The document formatting class could be subclassed by a renderering class, eg an html-formatter or a docstring-formatter. It so happens Jim has an intern looking at doing this restructuring as a fun-ish (relief from C coding) side project. It's not clear we'll get it done, but it is clear we'd be happy to see it, and i think it would allow a whole lot more customizability. > The use of single quotes to markup inline code (as in 'x') can be > surprising. Many current docstrings use 'x' to refer to the > *string* containing the character x, not the variable x. In > StructuredText, the quotes would dissappear in the rendering. With > practice, the current scheme could be used but users would have to > learn to write '"x"' to have their intent carry through to the > renderer. This is probably my biggest problem with StructuredText > because I don't know how to fix it while maintaining > compatibility. Related questions for Jim or Ken are 1) How does > StructuredText parse ''? 2) How can one have a single quote in > verbatim text? I can't answer all your questions. We'd be interested to know what you suggest as an alternative - how would you indicate brief <code> passages? It's possible the generic formatter would be settable to one or the other, or it'd recognize both ticked-code and whatever you want and the renderer would choose which to transform to code, or we'd have an almost generic formatter which could be derived into different flavors of generic formatters, each of which did the respective thing for recognizing short <code> passages. > The tagging of underlined text with _'s is suboptimal. Underlines > shouldn't be used from a typographic perspective (underlines were > designed to be used in manuscripts to communicate to the > typesetter that the text should be italicized -- no well-typeset > book ever uses underlines), and conflict with double-underscored > Python variable names (__init__ and the like), which would get > truncated and underlined when that effect is not desired. Note > that while *complete* markup would prevent that truncation > ('__init__'), I think of docstring markups much like I think of > type annotations -- they should be optional and above all do no > harm. In this case the underline markup does harm. Durn - i did that, and regret it. We're really not wedded to use of underscores for underlined text. > The requirement that a paragraph end with the word example or > examples or :: goes against my natural style, as I often do not > want such word or punctuation before a "displayed" paragraph. > Furthermore, the spec currently doesn't say how the renderer is > supposed to process the :: -- is it displayed as two colons, one, > or none? If the two colons are not displayed by the renderer, > then my objection is diminished, although I would have preferred a > markup which is local to the paragraph which is affected, not the > previous one (cut and paste errors follow too easily). In some > versions in the past at least, both colons were displayed. I'll > leave that as an open question, as additional markup could provide > an alternative which would suit me.r, which does the actual rendering. I think we agree that it'd be nice to have the example cue in the text, rather than before it, but we don't have a suggestion of a natural/uncluttered way to do that. As for the current :: format, to double colon is supposed to be rendered as a double colon. > Missing features: > [references to entities other than URLs; define namespaces for reference targets] Sounds cool. I think.-) > [list items without requring blank lines] Yay! > [tagged paragraphs] Might '::' example-style paragraphs fit into this category? Maybe provisions for special handling of the tag cue (E.g., throwing away "Example:") would enable this to solve our examples problem. > Technical points: > [regex has been deprecated] I think we would be ok with switchover to re if we had some kind of caching FormattedDocument, which may be in the works. But we use StructuredText enough in zope that performance is an issue - and re doesn't have the performance yet! Whoops - gotta run! Looking forward to more on this... Ken Manheimer klm(a)digicool.com

1 0

Pythondoc question
by Brad Chapman Jan. 24, 2000

Jan. 24, 2000

Hello all! I have just downloaded and started playing with pythondoc. It works beautifully for me for a single module and for the basic test programs in the distribution, but now I would like to try and use it to document my entire program, while is made up of a number of modules over a distributed directory structure. Is there an easy way to run pythondoc on all of the modules in my program at once? I guess this could be done by entering all of the module/file names that need to be pythondoced into the command line, but I would like a reusable way to do this--the program is still under heavy development and I would like to make it easy to keep the module documentation up to date with the program itself. Can the pythondoc.opts file be configured to have the names of all the programs to process? Thanks much for any help anyone can provide, and thanks for all the work on this wonderful program--it is much needed! Brad

1 0

IPC8 Developers Day discussion paper
by Fred L. Drake, Jr. Jan. 18, 2000

Jan. 18, 2000

I've posted the discussion document for the IPC Developers Day session; see it at: http://www.python.org/workshops/2000-01/doc-sig.html I hope to see you at the conference! -Fred -- Fred L. Drake, Jr. <fdrake at acm.org> Corporation for National Research Initiatives

1 0

Re: [Doc-SIG] Documentation systems for other languages
by Ken Manheimer Jan. 18, 2000

Jan. 18, 2000

On Fri, 7 Jan 2000 16:05:59 PST, bill janssen wrote: > Before that, (i think) edward welbourne wrote: > > For a pythonic system, folding would mean taking any fairly large chunk > > of code or doc (sharing a common base indent) and providing for it to be > > *displayed* (by the IDE) either (open fold) as the whole chunk or > > (closed fold) as a single line carrying (typically encoded as a comment) > > some text that says what's in the fold. In between, of course, we have > > the fold open but some portions of its contents folded out of sight. > > Most modern directory-browsers display directory tree hierarchies in a > > way instantly recognisable to anyone who ever used a folded editor. > > Sounds like outline mode in emacs. The GNU Emacs support for SGML > provides this, perhaps more closely resembling what you describe. I've been meaning to mention my outdent.el - it provides emacs outline-mode style text visibility control based on indentation, and runs as a minor mode - so you can run it in conjunction with python mode. I find it quite useful for looking at the structure of modules, especially large ones, and narrowing focus to particular portions. There are things yet to be done for it - searching can leave the cursor within hidden regions (so you need to hit ^C^I or ^C^S to expose where you are - interrupting the search), and i've been hoping for years to have a moment to incorporate this functionality directly in python-mode.el, but alas. It should be useful as is - it is for me... Find it at http://starship.python.net/crew/klm/outdent.el Ken Manheimer klm(a)i.am

2 4