Mailman 3 March 2006 - Doc-SIG

introducing the experimental pytut wiki
by Fredrik Lundh April 6, 2006

April 6, 2006

without further ado, here's http://pytut.infogami.com/ inspired by http://article.gmane.org/gmane.comp.python.general/455724 and related to several earlier threads on this mailing list. </F>

1 1

Re: [Doc-SIG] non-ascii docstrings
by Laura Creighton March 28, 2006

March 28, 2006

I have never seen a module where the -*- coding -*- is not the same as the docstring, either. And the greatest number of times I have seen this is where people are using some company-wide tool, possibly third-party and possibly to integrate with java code -- to extract the docstrings, and also have a requirement that the docstring contains the name of the person who wrote, and or modified the code. Indeed, in the matter of encoding, I wish that python would guess a whole lot more. One of the most common 'first python programs' that non-computer people write is 'my phonelist manager' and another is 'my cd collection manager'. I think that they have plenty enough to worry about without needing to find out about encodings before their first python program runs. Most places _have_ a locale sort of setting, and I would be in favour of trying whatever is there when encountering something that is not ascii. Laura

2 1

non-ascii docstrings
by Edward Loper March 25, 2006

March 25, 2006

I've been working on epydoc, and the question has come up of how I should treat non-unicode docstrings that contain non-ascii characters. An example of such a file is "python2.4/encodings/string_escape.py", whose module docstring contains an 'o' with an umlaut. In particular, the question is whether I should assume that the docstring is encoded with the encoding specified by the "-*- coding -*-" directive at the top of the file. The reason why we *wouldn't* use the encoding is that PEP 263 [1], which defines the coding directive, says that it does *not* apply to non-unicode string literals. In particular, PEP 263 says that the entire file should be read & tokenized using the specified coding, but once string objects are created, they should be reencoded back into 8-bit strings using the file encoding. So the "correct" fix is for the author of the module to use unicode literals instead of string literals for docstrings that contain non-ascii characters. This has the advantage that if a user tries to look at the docstring via introspection, it will be correct. On the other hand, epydoc is often used by people other than the author of a module, and requiring them to go through and replace all string literal docstrings with unicode literals seems a bit unreasonable. In a way, this is similar to the mistake I've seen many times of using non-escaped backslashes inside docstrings. e.g.: def wc(filename): """ Count the number of words in the given file. E.g.: >>> wc("c:\test\new.txt") 100 """ Which looks fine in the source file, but looks quite broken if you print its __doc__: >>> print wc.__doc__ Count the number of words in the given file. E.g.: >>> wc("c: est ew.txt") 100 (The right fix in that case is probably to use a raw-string.) So the question is.. Should epydoc (and other tools like it) be compliant with PEP 263 (and consistent with Python); or should they "do what I mean, not what I say" and treat non-ascii docstrings as if they were encoded using the module's encoding? -Edward http://www.python.org/doc/peps/pep-0263/

3 3

How should variables' docstrings be written?
by Edward Loper March 18, 2006

March 18, 2006

Epydoc 3 supports extracting information about Python modules by parsing. As a result, it can extract "docstrings" for variables. There are several possible ways these docstrings could be expressed in the Python source file, and I wanted to get some feedback on which ways people prefer. It's my hope that some consensus can be reached on this, so that any tools that extract variable docstrings can use the same conventions. The conventions I've seen are: class A: a = 1 """string literal following the assignment""" ## # Comment whose first line starts with a double-hash, # preceeding the assignment. b = 2 #: Comment that begins with a special marker string on all #: lines, preceeding the assignment c = 3 d = 4 #: Comment w/ marker on the same line the as assignment e = [ #: Comment w/ special marker, within the value expression. 1, 2, 3] String literal: This is the closest form to existing docstrings. I think it works well if the assignment line is fairly short, but for multiline values (eg large dictionaries or multiline strings), the docstring can become too far from the name of the variable it describes. Also, if the value is a multiline string, the division between the end of the value and the start of the docstring isn't obvious. Comment whose first line is a double hash: This is used by doxygen and Fredrik Lundh's PythonDoc. In doxygen, if there's text on the line with the double hash, it is treated as a summary string. I dislike this convention because it seems too likely to result in false positives. E.g., if you comment-out a region with a comment in it, you get a double-hash. Comment that begins with a special marker string: This is my current favorite. But there's a question of what the special marker string should be. Enthought proposes "#*", partially because it works well with line wrapping for some versions of emacs. But if a different marker string is deciced on, then python-mode.el could certainly be made aware of it. The markers that look reasonably good to my eye are: #: #| #* Currently, epydoc supports both string literals and comments with the special marker "#:". The comment-docstrings can be placed before the assignment, after it on the same line, or within the value (or any combination thereof). So.. Which conventions do people prefer? -Edward

4 5

coordination for translation of the Python Documentation
by Manlio Perillo March 14, 2006

March 14, 2006

Regards. There exists an effort to aid the coordination of the translations of the Python Documentation? Thanks Manlio Perillo

3 4

docutils, ReST, and pydoc
by John M. Gabriele March 7, 2006

March 7, 2006

Holy mackerel! I just read a good portion of PEP 287 http://www.python.org/peps/pep-0287.html and it seems clear to me that I should be able to put reStructured text right into my docstrings and then read them nicely rendered with the pydoc command. Is it a foregone conclusion that this functionality will soon be built into standard Python? If so, how long until that happens? What sticking points are we currently facing? I took a brief look at the docutils page. Is it possible that the project has bitten off more than it can chew? That is, it looks like they're building a very general tool, whereas Python may simply need to have pydoc properly render ReST in docstrings so I can run "pydoc some_module" and get some nice manpage-style (perldoc style) documentation right there in my terminal. Thanks, ---John __________________________________________________ Do You Yahoo!? Tired of spam? Yahoo! Mail has the best spam protection around http://mail.yahoo.com

4 3