Mailman 3 May 2004 - Doc-SIG

objections to renaming "--exit" option / "exit_level" setting?
by David Goodger June 3, 2004

June 3, 2004

Does anybody use the "exit_level" setting ("--exit" option)? I'm thinking of changing the names to better reflect the function. From docs/config.txt: """ exit_level A system message level threshold; non-halting system messages at or above this level will produce a non-zero exit status at normal exit. Exit status is the maximum system message level plus 10 (11 for INFO, etc.). Default: disabled (5). Options: ``--exit``. """ I think the option originally suggested by Beni Cherniavsky, "--exit-status", is better. I'd also change the setting to "exit_status_level". I'm sending this message to gauge the impact; will this break a lot of people's systems? -- David Goodger <http://python.net/~goodger>

2 1

``invisible`` reST-directive
by Felix Wiemann June 3, 2004

June 3, 2004

I propose adding a new directive 'invisible' to the reST-syntax, which translates to the already existing doctree element 'comment'. Thus, comments could be written as:: Normal text. .. invisible:: This is a comment. This still belongs to the comment. Normal text again. IMO it's much more intuitive than the '..' syntax for comments. When the '.. invisible::' directive is available and when it is being used, we can start phasing out the present comment syntax. At first, old-style comments can issue an informational system message, so that one can start replacing old-style comments (with '..') by the 'invisible::' directive. After some moths, we can start issuing a warning on old-style comments. Again after some months, we can maybe change the warnings to errors (that doesn't have to be decided now) and start allowing directives with a single colon:: .. image: foo.png ... which is IMO much easier to write and a little bit better to read. (Of course, there is no need to drop support for the old syntax with two colons.) The new directive-syntax with one colon is only possible after having phased out the old comment-syntax -- see the second point in <http://docutils.sourceforge.net/spec/rst/alternatives.html#reworking-explic…>. IMO an invisible-directive would be a good way to get rid of the the unintuitive and difficult-to-explain comment-syntax *and* the double-colon directive-syntax. What do you think? -- When replying to my email address, ensure that the mail header contains 'Felix Wiemann'. Please don't send unrequested mails > 64 KB. <http://www.ososo.de/>

3 7

Idea: make double-space between sentences meaningful
by Beni Cherniavsky May 24, 2004

May 24, 2004

Some formats (notably LaTeX) support the typographical convention (of some languages, e.g. English but not French IIRC) of putting a bigger space after the end of a sentence than between words. LaTeX tries to guess intellegently but can fail. Its guessing can be explicitly overriden [1]_. Currently, reST provides no way to convey this information to the output format. Producing high-quality output requires this information. There already exists an obvious convention supported by programs (e.g. Emacs) for representing it in plain text: just use a double space after the end of a sentence. I propose to make this official for reStructuredText: more than one space between words after punctuation [2]_ signifies a sentence end [3]_. Backward compatiblity: at worse, it will force all sentence ends to single spaces in existing documents that don't use the double-space convention in the reST source. It's a good bet that anybody who cares about it in his LaTeX output also cares about his source, but it's a good idea to make this a parser option (defaulting off?)... It is even possible, if desired, to support this in HTML output, using some hack (`` `` won't do because we *want* it to be breakable - it's even better there; perhaps ``<span class="sentence-end"> </span>`` with appropriate CSS?). .. [1] By using ``\@.`` for a sentence end and ``.\ `` for a sentence non-end. See `The Not So Short Introduction to LaTeX 2ε`__, section 2.6. __ http://www.ctan.org/tex-archive/info/lshort/english/lshort.pdf .. [2] Punctuation should be taken in a wide sense of the word. E.g. many people end a sentence with a smiley without putting a period after it ;-). .. [3] A period at end-of-line should be considered a sentence end per Emacs conventions (it acutally avoids putting non-sentence-end periods at end-of-line when refilling paragraphs!). However, if there is a trailing whitespace, it should be used to decide (in the style of RFC 2646 - wrap lines *after* the whitespace - which is the only unambiguos way to retain spacing info at line ends; some editors (pico/nano) use this only when there is more than one space - this algorithm will support them all). -- Beni Cherniavsky <cben(a)users.sf.net> Note: I can only read email on week-ends...

4 4

Attribute docstrings (was: [Docutils-develop] concerns over futureof codebase)
by Beni Cherniavsky May 18, 2004

May 18, 2004

[Moving this spin-off discussion to Doc-SIG where it belongs] David Goodger wrote: > David Abrahams wrote: > > David Goodger wrote: > > > document = None > > > """The document to write.""" > > > > Whaa?? This attribute is on the class, not an instance, if I > > remember my Python. It strikes me as meant to be per-instance data. > > What if you have several writers active at once? > > Notice that these variables are being set to None. I've updated the > docstrings with text like "set by `write`". They're initialized to > bogus values in the class scope because that's one of the places where > their docstrings will be recognized; see PEP 258. > What?!? You are initializing a value in code *only* because that's a precondition to the docstring being recognized? Not having seen the code, I can't say whether initializing it there is healthy on other merits -- but it certainly sounds bad that the documentation format forces you to write code in a certain way. > > """docstrings""" used in this way are discarded by Python, and > > should be replaced by comments preceding the variable IMO. I > > *think* that's what most people expect. > > PEP 258 describes "attribute docstrings"; for full details, see > <http://docutils.sf.net/spec/pep-0258.html#docstring-extraction-rules>, > item 2 ("Where"). > Let me join the "Urf" sentiment. I've resented this solution/syntax since I saw it for the following reasons: * It provides no way to introspect these docstrings. That's a design decision: Since attribute docstrings and additional docstrings are ignored by the Python byte-code compiler, no namespace pollution or runtime bloat will result from their use. but I disagree with the motivation. I can understand the desire for "secondary" docstrings to limit code bloat but who said that *all* attribute docstrings *must* be secondary? What if do want them at runtime (and I do)? Why shouldn't I have the option? + Instance variables can't have the docstring attached to the value (because the value comes and goes, the docstring is for the slot, not the value). Schemes like storing the docstring in `__doc_<name>__` are also ugly. I feel that attribute docstrings belong at the end of the class docstring. + If the attribute docstring is to be appended to the class docstring, it should be textually marked as belonging to the attribute. How to do it depends on the doc format one uses. E.g. for reST, a definition list is a natural choise:: Main class docsrting ... attr1 Doc for attr1 attr2 Doc for attr2 User control over the format is desirable. + It's not always convenient to document attributes one-by-one. There are usaully interactions between attributes, so there might be better ways to structure the documentation. It's the same sentiment that applies to comments - frequently a single comment covers several statements. * I don't like the syntax that is magically sensitive to assignments. I could stand that, but being magically sensitive to assignments to attributes of `self` in `__init__` is way too magical to be Pythonic IMHO. I'm not sure yet whether I like the docstring before or after the assignment - but probably before is better. Think of:: foo = [ long, {data: structure}, here ] """Docstring""" Does it belong there? No - for the same reasons we put comments that don't fit on the same line before the code: the code might be long. Anybody quoting the Python style for class/function docstrings as a precedent for putting the docstrings after the code forgets that the bulk of the class/function code comes after the docstring. It follows only the header line (for indentation aesthetics reasons), which is almost guaranteed to be short. That's another reason the after-assignment syntax is weak. There is no explicit connection of the docstring with the variable. If backward-compatibility was not an issue, the following syntax would solve this (but only this) issue:: attr = Value """Docstring""" For all these reasons, I propose the following extremely unmagical solution: all bare-string statements are simply concatenated together to form this scope's docstring. Well, not simply - at least a newline (or two?) should be inserted because most docstrings don't end with one. In other words, we simply allow the docstring to be split into parts with code between them, which brings docstrings one step closer to literate programming. The examples from `PEP 258`__ then become:: """g This is g's docstring.""" g = 'module attribute (module-global variable)' class AClass: """c This is AClass.c's docstring.""" c = 'class attribute' """i This is i's docstring.""" def __init__(self): """Method __init__'s docstring.""" self.i = 'instance attribute' def f(x): """Function f's docstring.""" return x**2 """a Function attribute f.a's docstring.""" f.a = 1 __ http://docutils.sf.net/spec/pep-0258.html#attribute-docstrings I had to pull the docstring for self.i out of `__init__`; this is somewhat unfortunate. OTOH I'm not sure the documentation of the attribute's *purpose* belongs with the initial assignment to it. If separating the docstring from the initialization is problematic, its separation from any other access to the attribute must be no less problematic... There is no difference in this scheme between documenting a class attribute and an instance attribute. If important, this is better documented in the docstring itself, because in Python there are many shades of it (e.g. class attributes might actually be defaults for instance attributes). The documentation of `f.a` is also torn away from it's assignment. But I find it extremely hard to image a situation where there is a special maining to an attribute of a specific function. The meaning of the attribute (`a`) would normally be common to all functions that have such an attribute. The meaning of the attribute's value (1) should be associated with the value (if it were a class/function, it would have it's own docstring; number won't have docstrings in the forseable future ;-). -- Beni Cherniavsky <cben(a)users.sf.net> Note: I can only read email on week-ends...

3 2

API doc tool
by David Goodger May 17, 2004

May 17, 2004

Howdy! I am writing from the offices of Enthought, in Austin Texas. Enthought is funding development work on an API documentation generation tool that they need, which they're releasing under a BSD-style license. I'm here for a week of planning and initial development. I will be completing the development part-time over the next several months. This is a great opportunity to make significant progress on the tool that I've been talking and thinking about for some time. There is a lot of good prior art that will be examined for this (Epydoc, HappyDoc, others). The initial basis of the tool will PEP 258's description of the Python Source Reader [1], but I'm sure there will be additions and changes as time goes on. What form the final tool takes is open to discussion right now, so feedback is welcome. [1] http://docutils.sf.net/spec/pep-0258.html#python-source-reader -- David Goodger

1 0

Re: Attribute docstrings
by Edward Loper May 17, 2004

May 17, 2004

Felix Wiemann wrote: >> Another problem is that it's currently impossible to assign a new value >> to an integer's docstring. >> >> >>> a = 5 >> >>> a.__doc__ = "new docstring" >> >> Traceback (most recent call last): >> File "<stdin>", line 1, in ? >> AttributeError: 'int' object attribute '__doc__' is read-only It's important to note that values and variables are fundamentally different things. Strictly speaking, only *values* can have docstrings (i.e., description strings accessible via .__doc__). It will *never* be possible to access variable docstrings via the variables themselves; as Beni noted, the only reasonable place to store description strings for variables (if we want them to be accessible via inspection) is in the enclosing object (either in its docstring or in some other attribute). To avoid confusion, let's call these variable-docstrings "pseudo- docstrings", to distinguish them from real docstrings (which are accessible via .__doc__). Beni Cherniavsky wrote: > For all these reasons, I propose the following extremely unmagical > solution: all bare-string statements are simply concatenated together to > form this scope's docstring. I've been going back and forth on whether I like this idea. I agree with Felix that writing each variable name twice is somewhat ugly. The main advantage of Beni's proposal is its simplicity. A number of subtle issues came up when I was writing the pseudo-docstrings extractor for epydoc. E.g., what do you do with... x,y = 1,2 """docstring""" x = y = 0 """docstring""" x[0] = 5 """docstring""" x.y = 5 """docstring""" x.y = z = 1,2 """docstring""" self.x = 10 """docstring""" (If you're curious, epydoc will write a shared description for the first two cases, ignore the 3rd and 4th case, and treat the last case as an instance variable, assuming it's in a class's __init__ and 'self' is equal to __init__'s first parameter name.) Using Beni's proposal, the programmer can handle these cases as they see fit. E.g.: """:Parameters x,y: docstring for x and y.""" x,y = 1,2 > Well, not simply - at least a newline (or > two?) should be inserted because most docstrings don't end with one. You'd also have to magically deduce the indentation for the first line of the docstring. And note that in the examples you gave, inspect.getdoc() will *not* give you what you want. E.g., the pesudo-docstring: """c This is Aclass.c's docstring.""" would get translated into: "c\nThis is Aclass.c's docstring" (note the lack of indentation on the second line). But leaving the indentation as-is will result in invalid ReST. This seems like a potential show-stopper to me, because it would basically mean that you need to add an extra CR for each attribute docstring: """ c This is Aclass.c's docstring.""" Besides looking ugly, this makes a 3-line docstring out of something that really should have been a one-liner. > I had to pull the docstring for self.i out of `__init__`; this is > somewhat unfortunate. If you made the rule "any bare string literal is appended to the containing namespace object (module or class) docstring," then you could put instance variable docstrings inside of __init__ methods. (Note that it doesn't make any sense to document a function's variable, because functions aren't namespaces.) > OTOH I'm not sure the documentation of the > attribute's *purpose* belongs with the initial assignment to it. But the good thing about pseudo-docstrings is that it lets the *programmer* decide where it's appropriate to document variables. Sometimes this will be in the containing object's docstring, sometimes this will be next to one of the assignments. Despite its appealing simplicity, my main problems with Beni's proposal are... - Duplication of variable names - It should be possible to write variable docstrings in one line (or less; see the psuedo-docstring for z, below). For comparison, I'm currently planning to extend epydoc to accept 3 formats for pseudo-docstrings: x = 12 """pseudo-docstring for x""" #: pseudo-docstring for y y = 20 z = 99 #: pseudo-docstring for z Where the "#:" sequence is used to disambiguate psuedo-docstrings from normal comments (I picked this sequence because it looked reasonable to me, but I'd be open to changing it if there's a reason to). Of course, these pseudo-docstrings won't be accessible via inspection; but I don't see that as a huge problem, as long as... - The tools that need them (e.g., epydoc/pydoc) can get at them. - Programmers *also* have the option of documenting variables in the containing namespace object. And if these formats become standard, then we can add a module the the stdlib to extract them. -Edward

1 0

Python 2.3.x doc tree closed
by Fred L. Drake, Jr. May 12, 2004

May 12, 2004

I'm cutting the docs for Python 2.3.4; please make no changes on the the release23-maint branch. Thanks for everyone's help in getting this ready! -Fred -- Fred L. Drake, Jr. <fdrake at acm.org> PythonLabs at Zope Corporation

1 0

Docutils 0.3.3 released
by Felix Wiemann May 11, 2004

May 11, 2004

Docutils 0.3.3 has been released. Read <http://docutils.sourceforge.net/#unstable-releases> for details. It's alpha software. However, many new features have been added and many bugs have been fixed since Docutils 0.3 (the latest 'stable' release), so you might very well consider using it (on non-production systems). (Posted to Doc-SIG and Docutils-users. Please direct discussion to Docutils-users.) -- When replying to my email address, ensure that the mail header contains 'Felix Wiemann'. Please don't send unrequested mails > 64 KB. <http://www.ososo.de/>

1 0

ReST: how to break at the end of each line?
by Pijus Virketis May 3, 2004

May 3, 2004

Dear all, I am writing my website's links page using ReST. The format I'd like to achieve is very simple: Python: favourite scripting language. ReST: neat text processing system. ... What I've got in the way of ReST is: `Python <http://www.python.org>`__ favourite scripting language. `ReST <http://docutils.sourceforge.net>`__ neat text processing system. So far, so good. The only problem is that when html.py renders the text, it puts everything on one line: Python: favourite scripting language. ReST: neat text processing system. I realise that this is the way a paragraph is supposed to be handled; but now I would like to insert breaks at the end of each line in a nice ReST-like way, without resorting to hacks. Literal block does not seem to be the ticket, since it does not process the ` <>`__ bit correctly. I'd appreciate any suggestions. Thank you! Pijus

2 1