classification
Title: Document IO module
Type: enhancement Stage:
Components: Documentation Versions: Python 3.0
process
Status: closed Resolution: accepted
Dependencies: Superseder:
Assigned To: benjamin.peterson Nosy List: benjamin.peterson, georg.brandl, gvanrossum, mark
Priority: critical Keywords: patch

Created on 2008-04-01 20:41 by benjamin.peterson, last changed 2008-04-13 12:30 by benjamin.peterson. This issue is now closed.

Files
File name Uploaded Description Edit
io_doc.patch benjamin.peterson, 2008-04-06 14:14
io_doc2.patch benjamin.peterson, 2008-04-06 16:32
io_doc3.patch benjamin.peterson, 2008-04-08 21:12
Messages (13)
msg64822 - (view) Author: Benjamin Peterson (benjamin.peterson) * (Python committer) Date: 2008-04-01 20:41
The IO module currently has some docs strings but no official RST docs.
I'm willing to work on this.
msg64971 - (view) Author: Georg Brandl (georg.brandl) * (Python committer) Date: 2008-04-05 13:38
Great!
msg65037 - (view) Author: Benjamin Peterson (benjamin.peterson) * (Python committer) Date: 2008-04-06 14:14
Attaching a draft.
msg65042 - (view) Author: Georg Brandl (georg.brandl) * (Python committer) Date: 2008-04-06 16:07
Looks good already! I can't review the full text now, but can you move
member documentation into the indented block for the class? (I know
other documents don't do this, but this is a legacy and I'd like new
documents to adopt this style.)

Additionally, the function description style is inconsistent ("Flushes
the stream" vs "Return this").
msg65044 - (view) Author: Benjamin Peterson (benjamin.peterson) * (Python committer) Date: 2008-04-06 16:32
Ok. attaching an improved patch. Do you think information about
indenting classes and such can be added to the style guide? It'd be very
helpful.
msg65217 - (view) Author: Benjamin Peterson (benjamin.peterson) * (Python committer) Date: 2008-04-08 21:12
Attaching an updated patch from a review Mark Summerfield.
msg65251 - (view) Author: Georg Brandl (georg.brandl) * (Python committer) Date: 2008-04-09 18:41
Reviewed, changed a few things and committed as r62252. Thanks!
msg65267 - (view) Author: Benjamin Peterson (benjamin.peterson) * (Python committer) Date: 2008-04-09 21:32
Georg, I have a few questions:
Just out of curiosity, what did you change? Are their markup things I
missed or other things you're looking for that I just didn't get?

Are we going to want to push some of this stuff back into the docstrings?

Should I backport this to 2.6?

Mark: It has been checked in.
msg65271 - (view) Author: Georg Brandl (georg.brandl) * (Python committer) Date: 2008-04-09 22:10
Other than the "class.method" change you already noticed, I changed some
"method"s to "attribute"s (since they are @propertied in the source),
removed parens in :meth:`` roles, moved the constructor description into
the .. class block and did some spelling corrections.

A backport to 2.6 would be great. If you also find time to put some
docstrings in, very good.
msg65284 - (view) Author: Benjamin Peterson (benjamin.peterson) * (Python committer) Date: 2008-04-10 02:03
When you remove the class from the method declaration, it shows up in
the html as io.write? Is this correct?
msg65409 - (view) Author: Georg Brandl (georg.brandl) * (Python committer) Date: 2008-04-12 18:13
It isn't. I'll have to investigate this -- I have a feeling of déjà-bug...
msg65438 - (view) Author: Georg Brandl (georg.brandl) * (Python committer) Date: 2008-04-13 08:02
Should be fixed now with the latest Sphinx revision.
msg65443 - (view) Author: Benjamin Peterson (benjamin.peterson) * (Python committer) Date: 2008-04-13 12:30
And I have fleshed out the doc strings and backported it to 2.6.
History
Date User Action Args
2008-04-13 12:30:52benjamin.petersonsetmessages: + msg65443
2008-04-13 08:02:07georg.brandlsetmessages: + msg65438
2008-04-12 18:13:26georg.brandlsetmessages: + msg65409
2008-04-10 02:03:11benjamin.petersonsetmessages: + msg65284
2008-04-09 22:10:26georg.brandlsetmessages: + msg65271
2008-04-09 21:32:47benjamin.petersonsetnosy: + mark
messages: + msg65267
2008-04-09 18:41:43georg.brandlsetstatus: open -> closed
resolution: accepted
messages: + msg65251
2008-04-08 21:12:36benjamin.petersonsetfiles: + io_doc3.patch
messages: + msg65217
2008-04-06 16:32:14benjamin.petersonsetfiles: + io_doc2.patch
messages: + msg65044
2008-04-06 16:07:35georg.brandlsetnosy: + gvanrossum
messages: + msg65042
2008-04-06 14:14:08benjamin.petersonsetfiles: + io_doc.patch
keywords: + patch
messages: + msg65037
2008-04-05 13:38:33georg.brandlsetmessages: + msg64971
2008-04-01 20:41:46benjamin.petersoncreate