Mailman 3 [issue9302] Distutils document problem? - docs

newer
[issue12195] Little documentation...

[issue9302] Distutils document problem?

Ray.Allen

19 Jul 2010 19 Jul '10

9:43 a.m.

New submission from Ray.Allen : The distutils api document for class Extension: http://docs.python.org/dev/py3k/distutils/apiref.html#distutils.core.Extensi... Among the argument, in fact, the type of the arguments "sources", "include_dirs", "library_dirs", "libraries", "runtime_library_dirs" must be list, but all of them are marked as "string". I think this is a problem. Here is a patch for this, against py3k. ---------- assignee: docs@python components: Documentation files: distutils_apiref.diff keywords: patch messages: 110724 nosy: docs@python, ysj.ray priority: normal severity: normal status: open title: Distutils document problem? versions: Python 3.2 Added file: http://bugs.python.org/file18061/distutils_apiref.diff _______________________________________ Python tracker http://bugs.python.org/issue9302 _______________________________________

Show replies by date

R. David Murray

19 Jul 19 Jul

12:41 p.m.

Changes by R. David Murray : ---------- nosy: +tarek _______________________________________ Python tracker http://bugs.python.org/issue9302 _______________________________________

Éric Araujo

21 Mar 21 Mar

1:18 a.m.

New subject: [issue9302] distutils.core.Extension: list parameters documented as strings

Éric Araujo added the comment: Thanks for the catch. Are there no similar problems in the rest of the distutils doc, or did you search in one file only? ---------- assignee: docs@python -> eric.araujo components: +Distutils, Distutils2 nosy: +alexis, eric.araujo stage: -> patch review title: Distutils document problem? -> distutils.core.Extension: list parameters documented as strings versions: +3rd party, Python 2.7, Python 3.1, Python 3.3 _______________________________________ Python tracker http://bugs.python.org/issue9302 _______________________________________

Ray.Allen

1:22 p.m.

New subject: [issue9302] distutils API Reference: setup() and Extension parameters' description not correct.

Ray.Allen added the comment: I searched the distutils docs for such a parameter description table and find tow more on the distutils.core.setup() function descriptions. Reflected in my updated patch. ---------- title: distutils.core.Extension: list parameters documented as strings -> distutils API Reference: setup() and Extension parameters' description not correct. Added file: http://bugs.python.org/file21323/issue_9302.diff _______________________________________ Python tracker http://bugs.python.org/issue9302 _______________________________________

Éric Araujo

6 Jun 6 Jun

4:12 p.m.

New subject: [issue9302] distutils API Reference: setup() and Extension parameters' description not correct.

Changes by Éric Araujo : ---------- status: open -> pending _______________________________________ Python tracker http://bugs.python.org/issue9302 _______________________________________

R. David Murray

10:55 p.m.

New subject: [issue9302] distutils API Reference: setup() and Extension parameters' description not correct.

R. David Murray added the comment: Why was this issue set to pending? No motivating comment was added. ---------- nosy: +r.david.murray status: pending -> open _______________________________________ Python tracker http://bugs.python.org/issue9302 _______________________________________

Éric Araujo

7 Jun 7 Jun

3:07 p.m.

New subject: [issue9302] distutils API Reference: setup() and Extension parameters' description not correct.

Éric Araujo added the comment: Sorry, I thought updating the status was enough to convey “I’m about to commit this”. ---------- versions: -Python 3.1 _______________________________________ Python tracker http://bugs.python.org/issue9302 _______________________________________

R. David Murray

3:14 p.m.

New subject: [issue9302] distutils API Reference: setup() and Extension parameters' description not correct.

R. David Murray added the comment: Um, no. 'pending' is 'pending close', specifically meaning, 'this issue is going to be closed (with a rejected status of some sort) unless someone objects or provides more information.' Someday, pending issues will be autoclosed after N days. Quite possibly this summer, since Ezio is working on roundup this summer. ---------- _______________________________________ Python tracker http://bugs.python.org/issue9302 _______________________________________

Éric Araujo

3:35 p.m.

New subject: [issue9302] distutils API Reference: setup() and Extension parameters' description not correct.

Éric Araujo added the comment: Oh, thanks for clearing a misunderstanding I’ve had for a year! I was using the pending status to prioritize issues (I have a personal “assigned to me + pending” query, now I’ll use priority instead. ---------- _______________________________________ Python tracker http://bugs.python.org/issue9302 _______________________________________

Éric Araujo

3:35 p.m.

New subject: [issue9302] distutils API Reference: setup() and Extension parameters' description not correct.

Éric Araujo added the comment: This also explains why any new message cancels the pending status, BTW. ---------- _______________________________________ Python tracker http://bugs.python.org/issue9302 _______________________________________

Éric Araujo

16 Jun 16 Jun

3:07 p.m.

New subject: [issue9302] distutils API Reference: setup() and Extension parameters' description not correct.

Éric Araujo added the comment: FYI, in one packaging doc I added one note instead of changing each cell: http://docs.python.org/dev/library/packaging.compiler#id6 ---------- _______________________________________ Python tracker http://bugs.python.org/issue9302 _______________________________________

ysj.ray

3:22 p.m.

New subject: [issue9302] distutils API Reference: setup() and Extension parameters' description not correct.

ysj.ray added the comment:

...

FYI, in one packaging doc I added one note instead of changing each cell: http://docs.python.org/dev/library/packaging.compiler#id6

I like this solution, it seems more concise and to the point. With this the doc need only one change: --- a/Doc/distutils/apiref.rst Fri Apr 29 14:07:28 2011 +0800 +++ b/Doc/distutils/apiref.rst Thu Jun 16 23:15:12 2011 +0800 @@ -85,15 +85,15 @@ | *script_args* | Arguments to supply to the | a list of strings | | | setup script | | +--------------------+--------------------------------+-------------------------------------------------------------+ - | *options* | default options for the setup | a string | + | *options* | default options for the setup | a dictionary | | | script | | +--------------------+--------------------------------+-------------------------------------------------------------+ ---------- _______________________________________ Python tracker http://bugs.python.org/issue9302 _______________________________________

Éric Araujo

3:26 p.m.

New subject: [issue9302] distutils API Reference: setup() and Extension parameters' description not correct.

Éric Araujo added the comment: Thanks for your feedback. My patch assumes that people will understand that an argument that has a plural name (like macros) can’t be a string but a list of strings; I don’t know if relying on this inference is better than your initial patch. An alternate style that I saw somewhere is to use “[str]” to describe a list of strings. ---------- _______________________________________ Python tracker http://bugs.python.org/issue9302 _______________________________________

R. David Murray

4:01 p.m.

New subject: [issue9302] distutils API Reference: setup() and Extension parameters' description not correct.

R. David Murray added the comment: I would not read [str] as implying a list of strings, FWIW. Nor would I assume a plural option meant a list if the text says "a string". But I'm just a bystander here and haven't even looked the docs you guys are updating :) ---------- _______________________________________ Python tracker http://bugs.python.org/issue9302 _______________________________________

Éric Araujo

4:11 p.m.

New subject: [issue9302] distutils API Reference: setup() and Extension parameters' description not correct.

Éric Araujo added the comment:

...

Nor would I assume a plural option meant a list if the text says "a string".

Especially in distutils code where we can get space-separated or comma-separated values from the command line or config files. I’m in favor of using explicit “list of strings” wording now. ysj.ray, I understand from the “Done” comments on the review page that you have an updated patch somewhere; please upload and I’ll commit. ---------- _______________________________________ Python tracker http://bugs.python.org/issue9302 _______________________________________

ysj.ray

17 Jun 17 Jun

2:31 a.m.

New subject: [issue9302] distutils API Reference: setup() and Extension parameters' description not correct.

ysj.ray added the comment:

...

I would not read [str] as implying a list of strings, FWIW.

help() on distutils.extension.Extension gives the parameters description like this: ...... sources: [string] ...... include_dirs: [string] ...... So I guess this style can be used as somewhere.

...

I’m in favor of using explicit “list of strings” wording now. ysj.ray, I understand from the “Done” comments on the review page that you have an updated patch somewhere; please upload and I’ll commit.

Ok, here is it. Thanks! ---------- Added file: http://bugs.python.org/file22391/issue_9302_2.diff _______________________________________ Python tracker http://bugs.python.org/issue9302 _______________________________________

Roundup Robot

26 Aug 26 Aug

2:32 p.m.

New subject: [issue9302] distutils API Reference: setup() and Extension parameters' description not correct.

Roundup Robot added the comment: New changeset 96f0ccb9716d by Éric Araujo in branch '3.2': Fix type information in distutils API reference (#9302). http://hg.python.org/cpython/rev/96f0ccb9716d New changeset a410b857efe3 by Éric Araujo in branch 'default': Merge from 3.2 (#9302 fix and other changes) http://hg.python.org/cpython/rev/a410b857efe3 New changeset 59b3f845f7a3 by Éric Araujo in branch 'default': Synchronize packaging docs with distutils’ (includes fix for #9302) http://hg.python.org/cpython/rev/59b3f845f7a3 ---------- nosy: +python-dev _______________________________________ Python tracker http://bugs.python.org/issue9302 _______________________________________

Roundup Robot

2:37 p.m.

New subject: [issue9302] distutils API Reference: setup() and Extension parameters' description not correct.

Roundup Robot added the comment: New changeset 78b26e7720c0 by Éric Araujo in branch '2.7': Fix type information in distutils API reference (#9302). http://hg.python.org/cpython/rev/78b26e7720c0 ---------- _______________________________________ Python tracker http://bugs.python.org/issue9302 _______________________________________

Éric Araujo

3:20 p.m.

New subject: [issue9302] distutils API Reference: setup() and Extension parameters' description not correct.

Éric Araujo added the comment: Improved and committed, thanks again! ---------- resolution: -> fixed stage: patch review -> committed/rejected status: open -> closed _______________________________________ Python tracker http://bugs.python.org/issue9302 _______________________________________

4625

Age (days ago)

5028

Last active (days ago)

List overview

Download

18 comments

5 participants

participants (5)

R. David Murray
Ray.Allen
Roundup Robot
ysj.ray
Éric Araujo

[issue9302] Distutils document problem?

tags

participants (5)