Mailman 3 August 2008 - Doc-SIG

Proposal: don't nest optional brackets
by A.M. Kuchling Sept. 26, 2008

Sept. 26, 2008

To show a series of optional parameters, currently we nest square brackets. http://docs.python.org/dev/library/warnings.html#warnings.filterwarnings warnings.filterwarnings(action[, message[, category[, module[, lineno[, append]]]]]) My proposal is that we drop the nesting and write this as: warnings.filterwarnings(action [, message, category, module, lineno, append]) Currently the stylesheets make the brackets very big and dark, so I've also added a space before the bracket. This change means we'd lose the ability to show when two optional arguments must be supplied at the same time, which could currently be written like this: warnings.filterwarnings(action[, message, category[, module]]) In this hypothetical example, if you supply 'message' you must also supply 'category'. But I think that for most functions, you can supply each optional argument or not; you rarely need to supply two optional arguments that are tied in this way, and we can handle such cases by adding a sentence such as "Both message and category parameters must be supplied." A few places (difflib, doctest, probably others) use this format: .. function:: context_diff(a, b[, fromfile][, tofile][, fromfiledate][, tofiledate][, n][, lineterm]) It's better than the nested version -- at least it avoids the ]]]]]) at the end -- but I think having a single set of square brackets also works and reduces the symbolic noise further. .. function:: context_diff(a, b [, fromfile, tofile, fromfiledate, tofiledate, n, lineterm]) The brackets are large enough that I think this would still be quite readable; it doesn't seem likely that readers will miss that these parameters are optional. What does everyone think? --amk

8 9

What to do next for 2.6?
by A.M. Kuchling Aug. 31, 2008

Aug. 31, 2008

This weekend I made a final revision pass over the 2.6 "What's New" document and am now finished with it (barring any small corrections or omissions that come in). What should I do now with my Python doc time? Georg, do you have any suggestions? I could start reading through one of the manuals from end-to-end or go through the bug tracker for doc items. Are there any writing-related tasks you've been meaning to do before 2.6final? --amk

4 4

Re: [Doc-SIG] What to do next for 2.6?
by Laura Creighton Aug. 31, 2008

Aug. 31, 2008

In a message of Sun, 31 Aug 2008 14:22:04 EDT, "A.M. Kuchling" writes: >This weekend I made a final revision pass over the 2.6 "What's New" >document and am now finished with it (barring any small corrections or >omissions that come in). > >What should I do now with my Python doc time? Georg, do you have any >suggestions? I could start reading through one of the manuals from >end-to-end or go through the bug tracker for doc items. Are there any >writing-related tasks you've been meaning to do before 2.6final? > >--amk What is the status of the tutorial? Laura

1 0

Increasing size of the monospace font
by A.M. Kuchling Aug. 30, 2008

Aug. 30, 2008

Here's what the current 2.6 docs look like on Firefox 3.0 under MacOS: http://www.flickr.com/photos/44165698@N00/2810698647/sizes/o/ The class names in the text are a good deal smaller than the English text. Is this just an oddity of my current configuration, or does it look like this for everyone? Here's what the docs look like after changing the font size for <tt> from 0.95 em to 1.25em: http://www.flickr.com/photos/44165698@N00/2811539974/sizes/o/ I think this makes the class names match the x-height of the prose much better, though now the boldface makes them look very dark. --amk

3 2

Re: [Doc-SIG] structured function documentation: preferred markup? (AC)
by Edward Loper Aug. 28, 2008

Aug. 28, 2008

> In order to simplify maintenance, I'm committed to providing structured > documentation for all of my code. [...] > > However, that seems excessively verbose due to the separate line for type > information. Hi, I'm the author of epydoc. I just wanted to mention that the next item on my to-do list for epydoc is to add support for the following syntax: @param bar (str): description of bar... The analogous syntax would also be supported for restructuredtext: :param bar (str): description of bar... Note that you can already do the following in epydoc when using restructuredtext: :parameters: bar : str description of bar... baz: int description of baz... My guess is that it'll be a couple weeks before I get time to implement this, if you can wait that long. As for whether there's a standard markup for docstrings -- not really. Be sure to define the __docformat__ module-level variable, so that any program like epydoc can tell what markup language you're using. E.g.: __docformat__ = 'restructuredtext' or __docformat__ = 'epytext' My personal recommendation would be to use epytext if you're happy with a very lightweight markup language that doesn't support many advanced features (tables, images, etc); or restructuredtext otherwise. Both epytext and restructuredtext are quite human-readable, even for people who are not familiar with the markup languages, which I think is important. -Edward

2 1

structured function documentation: preferred markup?
by AC Aug. 28, 2008

Aug. 28, 2008

Hello, First of all, I hope this is the right group to ask this in. My apologies if that's not the case. In order to simplify maintenance, I'm committed to providing structured documentation for all of my code. However, I'm not sure which markup language is preferred in the Python world - or whether there is any consensus at all. I'm currently using Epytext: def foo(bar): """ lorem ipsum dolor sit amet @param bar: consectetur adipisicing elit @type bar: str @return: None @rtype : None """ pass However, that seems excessively verbose due to the separate line for type information. I know there are alternatives (namely, Javadoc and reStructuredText) - but if they're not widely used, there's not much sense in me using those.* Any guidance would be greatly appreciated! * I know that Epydoc, for example, can generate documentation from various markup languages - however, my main concerns is the documentation directly within the source code

1 1