pypi/packages/docs.python.org
On Sun, Mar 6, 2011 at 20:49, cool-RR
Speaking of names, I would rename PyPI to packages.python.org, maybe move the existing documentation center to docs.python.org, and then move the docs of Python itself to a `/python` folder... But that's just me.
No, I do think docs.python.org should be for documentation of Python. I agree having package documentation on packages.python.org may not be very pedagogical, though. :-) //Lennart
On Sun, Mar 6, 2011 at 10:10 PM, Lennart Regebro
On Sun, Mar 6, 2011 at 20:49, cool-RR
wrote: Speaking of names, I would rename PyPI to packages.python.org, maybe move the existing documentation center to docs.python.org, and then move the docs of Python itself to a `/python` folder... But that's just me.
No, I do think docs.python.org should be for documentation of Python. I agree having package documentation on packages.python.org may not be very pedagogical, though. :-)
//Lennart
We must remember that what is obvious for us is *not* obvious for newbies. For us it's obvious that Python packages are on PyPI and that packages.python.org is documentation. But for, say, a Java programmer who's just touching Python for a small project, this is a possible point of confusion which can make him think, "Man, Python people are weird, what is this 'pypi' thing?" Ram. -- Sincerely, Ram Rachum
On Sun, Mar 6, 2011 at 9:10 PM, Lennart Regebro
On Sun, Mar 6, 2011 at 20:49, cool-RR
wrote: Speaking of names, I would rename PyPI to packages.python.org, maybe move the existing documentation center to docs.python.org, and then move the docs of Python itself to a `/python` folder... But that's just me.
No, I do think docs.python.org should be for documentation of Python. I agree having package documentation on packages.python.org may not be very pedagogical, though. :-)
One thing I find weird is the root page of packages.python.org -- This warning is not super user friendly. That said, maybe projects documentation could simply be displayed under their pypi.python.org/pypi root page, and packages.python.org made an alias to pypi.python.org
//Lennart _______________________________________________ Distutils-SIG maillist - Distutils-SIG@python.org http://mail.python.org/mailman/listinfo/distutils-sig
-- Tarek Ziadé | http://ziade.org
One thing I find weird is the root page of packages.python.org -- This warning is not super user friendly.
What particular clause strikes you as particularly unfriendly? Please understand that it may sound harsh, but is necessary - better be safe than sorry.
That said, maybe projects documentation could simply be displayed under their pypi.python.org/pypi root page, and packages.python.org made an alias to pypi.python.org
Not sure I understand the proposal. What URL would distribute get (say)? (i.e. what is distribute's "pypi.python.org/pypi root page"?) If "http://pypi.python.org/pypi/distribute", what would you do with the content that is currently displayed there? Regards, Martin
On Sun, Mar 6, 2011 at 10:42 PM, "Martin v. Löwis"
One thing I find weird is the root page of packages.python.org -- This
warning is not super user friendly.
What particular clause strikes you as particularly unfriendly? Please understand that it may sound harsh, but is necessary - better be safe than sorry.
I think it's less about the content and more about the form. I think this warning belongs in a little `legal` section at the bottom, not as the first thing that a visitor sees.
That said, maybe projects documentation could simply be displayed
under their pypi.python.org/pypi root page, and packages.python.org made an alias to pypi.python.org
Not sure I understand the proposal. What URL would distribute get (say)? (i.e. what is distribute's "pypi.python.org/pypi root page"?) If "http://pypi.python.org/pypi/distribute", what would you do with the content that is currently displayed there?
Regards, Martin
_______________________________________________ Distutils-SIG maillist - Distutils-SIG@python.org http://mail.python.org/mailman/listinfo/distutils-sig
-- Sincerely, Ram Rachum
I think it's less about the content and more about the form. I think this warning belongs in a little `legal` section at the bottom, not as the first thing that a visitor sees.
Are we talking about the same document? On http://packages.python.org/ the warning *is* in the bottom of the page (not that the page has much content in the first place). If you want it in a `legal` section at the bottom - that is easy (I just did it). Regards, Martin
On Sun, Mar 6, 2011 at 10:53 PM, "Martin v. Löwis"
I think it's less about the content and more about the form. I think
this warning belongs in a little `legal` section at the bottom, not as the first thing that a visitor sees.
Are we talking about the same document? On
the warning *is* in the bottom of the page (not that the page has much content in the first place).
Haha, well I guess it's technically at the bottom, but since the page is (a) almost empty and (b) looks like a text file, it kinda looks like the main content of the page.
If you want it in a `legal` section at the bottom - that is easy (I just did it).
That's somewhat of an improvement. A link to a separate legal statement, like on python.org, would be nice. But I understand that this will require some work that you may not have time to do.
Regards, Martin
-- Sincerely, Ram Rachum
On Sun, Mar 6, 2011 at 21:42, "Martin v. Löwis"
One thing I find weird is the root page of packages.python.org -- This warning is not super user friendly.
What particular clause strikes you as particularly unfriendly?
It's rather the lack of design and just a link that seems a bit... "raw" I guess. Could we have a list of packages than have documentation, maybe? No, scratch that, people will think that's all packages that exist. Also not good.
Not sure I understand the proposal. What URL would distribute get (say)? (i.e. what is distribute's "pypi.python.org/pypi root page"?) If "http://pypi.python.org/pypi/distribute", what would you do with the content that is currently displayed there?
I guess either http://pypi.python.org/pypi/distribute/docs or http://pypi.python.org/docs/distribute would be acceptable. Personally I don't think it's a big deal, but yes, I'm sure people go to packages.python.org expecting what they get on pypi. //Lennart
I guess either http://pypi.python.org/pypi/distribute/docs or http://pypi.python.org/docs/distribute would be acceptable.
The former won't work - it tries to get a version labeled "docs" from "distribute". As for the latter, see http://mail.python.org/pipermail/catalog-sig/2008-August/001723.html I originally proposed what you are proposing now, and Ian Bicking told me use what we have now because of XSS concerns (take and remove a plural form). Regards, Martin
On Sun, Mar 6, 2011 at 22:05, "Martin v. Löwis"
I guess either http://pypi.python.org/pypi/distribute/docs or http://pypi.python.org/docs/distribute would be acceptable.
The former won't work - it tries to get a version labeled "docs" from "distribute". As for the latter, see
http://mail.python.org/pipermail/catalog-sig/2008-August/001723.html
I originally proposed what you are proposing now, and Ian Bicking told me use what we have now because of XSS concerns (take and remove a plural form).
Ah, right, of course. So it needs to be a separate hostname. It's then only a question of what hostname. //Lennart
On Sun, Mar 6, 2011 at 9:42 PM, "Martin v. Löwis"
One thing I find weird is the root page of packages.python.org -- This warning is not super user friendly.
What particular clause strikes you as particularly unfriendly? Please understand that it may sound harsh, but is necessary - better be safe than sorry.
Nothing wrong about the warning itself, but about landing on a plain condensed text page. I think we should make it a html page. And maybe display the last ten packages doc updates ?
That said, maybe projects documentation could simply be displayed under their pypi.python.org/pypi root page, and packages.python.org made an alias to pypi.python.org
Not sure I understand the proposal. What URL would distribute get (say)? (i.e. what is distribute's "pypi.python.org/pypi root page"?) If "http://pypi.python.org/pypi/distribute", what would you do with the content that is currently displayed there?
so Distribute has currently: "http://pypi.python.org/pypi/distribute" It's the Description field of the metadata. And then we push our doc at: "http://packages.python.org/distribute/" Since "packages.python.org" allow us to have a directory with HTML files, those could be made accessible under: http://pypi.python.org/pypi/distribute/docs, with a big link on the top of http://pypi.python.org/pypi/distribute to go there. So: http://packages.python.org/PROJECT/ would become http://pypi.python.org/pypi/PROJECT/doc IOW, not changes but just avoiding two places -- without giving any hint on each place about the existence of the other place. Why Distribute would have two root pages ? http://pypi.python.org/pypi/distribute is a fine one Then, maybe http://pypi.python.org/pypi could simply become http://packages.python.org, with: - http://packages.python.org/PROJECT - http://packages.python.org/PROJECT/docs - http://packages.python.org/PROJECT/1.2 - etc..
Regards, Martin _______________________________________________ Distutils-SIG maillist - Distutils-SIG@python.org http://mail.python.org/mailman/listinfo/distutils-sig
-- Tarek Ziadé | http://ziade.org
2011/3/6 Tarek Ziadé
On Sun, Mar 6, 2011 at 9:42 PM, "Martin v. Löwis"
wrote: One thing I find weird is the root page of packages.python.org -- This warning is not super user friendly.
What particular clause strikes you as particularly unfriendly? Please understand that it may sound harsh, but is necessary - better be safe than sorry.
Nothing wrong about the warning itself, but about landing on a plain condensed text page. I think we should make it a html page. And maybe display the last ten packages doc updates ?
That said, maybe projects documentation could simply be displayed under their pypi.python.org/pypi root page, and packages.python.org made an alias to pypi.python.org
Not sure I understand the proposal. What URL would distribute get (say)? (i.e. what is distribute's "pypi.python.org/pypi root page"?) If "http://pypi.python.org/pypi/distribute", what would you do with the content that is currently displayed there?
so Distribute has currently: "http://pypi.python.org/pypi/distribute"
It's the Description field of the metadata.
And then we push our doc at: "http://packages.python.org/distribute/"
Since "packages.python.org" allow us to have a directory with HTML files, those could be made accessible under:
http://pypi.python.org/pypi/distribute/docs, with a big link on the top of http://pypi.python.org/pypi/distribute to go there.
So:
http://packages.python.org/PROJECT/ would become http://pypi.python.org/pypi/PROJECT/doc
IOW, not changes but just avoiding two places -- without giving any hint on each place about the existence of the other place.
Why Distribute would have two root pages ? http://pypi.python.org/pypi/distribute is a fine one
Then, maybe http://pypi.python.org/pypi could simply become http://packages.python.org, with:
- http://packages.python.org/PROJECT - http://packages.python.org/PROJECT/docs - http://packages.python.org/PROJECT/1.2 - etc..
+1 Ram
What particular clause strikes you as particularly unfriendly? Please understand that it may sound harsh, but is necessary - better be safe than sorry.
Nothing wrong about the warning itself, but about landing on a plain condensed text page. I think we should make it a html page. And maybe display the last ten packages doc updates ?
It actually *is* a html page (and always was). It just doesn't use any styling. As for changing the style: please submit a html file to replace what is there (I refuse to do any styling . As for displaying the last ten doc updates: either submit a tracker request, or provide a patch.
Since "packages.python.org" allow us to have a directory with HTML files, those could be made accessible under:
http://pypi.python.org/pypi/distribute/docs, with a big link on the top of http://pypi.python.org/pypi/distribute to go there.
[I wonder why "links" and "buttons" always have to be "big", and often "red" :-] See my response to Lennart for the former: distribute/docs would be the "docs" release of "distribute". As for a big link: if you think your page should have one, you are free to make it yourself already.
http://packages.python.org/PROJECT/ would become http://pypi.python.org/pypi/PROJECT/doc
IOW, not changes but just avoiding two places -- without giving any hint on each place about the existence of the other place.
Why Distribute would have two root pages ?
See above: what you propose cannot work. Also, I don't think many users care about the URLs of things. If your package home page is pypi/distribute, that's perfectly fine. Put a documentation link on that page, and be done.
Then, maybe http://pypi.python.org/pypi could simply become http://packages.python.org, with:
- http://packages.python.org/PROJECT - http://packages.python.org/PROJECT/docs - http://packages.python.org/PROJECT/1.2 - etc..
That would break existing packages URLs, so -1. You cannot lightly change URLs in the Web - replacing an existing URL is a multi-year project. Individual package maintainers may do, but we still get lots of hits on cheeseshop.python.org, so that needs to be supported many years in the future. I'm not looking forward to having a *second* transitional URL. Regards, Martin
2011/3/6 "Martin v. Löwis"
What particular clause strikes you as particularly unfriendly? Please understand that it may sound harsh, but is necessary - better be safe than sorry.
Nothing wrong about the warning itself, but about landing on a plain condensed text page. I think we should make it a html page. And maybe display the last ten packages doc updates ?
It actually *is* a html page (and always was). It just doesn't use any styling.
As for changing the style: please submit a html file to replace what is there (I refuse to do any styling . As for displaying the last ten doc updates: either submit a tracker request, or provide a patch.
That could be a nice small sprint task at Pycon -- will see
Since "packages.python.org" allow us to have a directory with HTML files, those could be made accessible under:
http://pypi.python.org/pypi/distribute/docs, with a big link on the top of http://pypi.python.org/pypi/distribute to go there.
[I wonder why "links" and "buttons" always have to be "big", and often "red" :-]
See my response to Lennart for the former: distribute/docs would be the "docs" release of "distribute".
Yes, good points.
As for a big link: if you think your page should have one, you are free to make it yourself already.
Sure but, 1/ I have never asked for the "Downloads ↓" link either, but the UI did add it, and it's really more ergonomic. 2/ I have never asked for "Latest Version: 0.6.14" on this page : hit ttp://pypi.python.org/pypi/distribute/0.6.9 and you also say for 2/ "if you think your page should have links to older releases, you are free to make it yourself already" But same remark: it makes browsing more friendly. And I think a link to packages.python.org/distribute is at the same level -- Tarek Ziadé | http://ziade.org
As for a big link: if you think your page should have one, you are free to make it yourself already.
Sure but,
1/ I have never asked for the "Downloads ↓" link either, but the UI did add it, and it's really more ergonomic.
2/ I have never asked for "Latest Version: 0.6.14" on this page : hit ttp://pypi.python.org/pypi/distribute/0.6.9 [...] And I think a link to packages.python.org/distribute is at the same level
I can sympathize with that view. Cc'ing catalog-sig here: if anybody would *not* want to have a "Documentation" link automatically generated that points to packages.python.org/<project>, please speak up. Regards, Martin
"Martin v. Löwis" wrote:
As for a big link: if you think your page should have one, you are free to make it yourself already.
Sure but,
1/ I have never asked for the "Downloads ↓" link either, but the UI did add it, and it's really more ergonomic.
2/ I have never asked for "Latest Version: 0.6.14" on this page : hit ttp://pypi.python.org/pypi/distribute/0.6.9 [...] And I think a link to packages.python.org/distribute is at the same level
I can sympathize with that view. Cc'ing catalog-sig here:
if anybody would *not* want to have a "Documentation" link automatically generated that points to packages.python.org/<project>, please speak up.
That would only make sense if there's something uploaded to the PyPI docs dir. If PyPI can detect that, +1. Otherwise, I think it's better not adding such an automatic link, since no link is better than one going nowhere. -- Marc-Andre Lemburg eGenix.com Professional Python Services directly from the Source (#1, Mar 06 2011)
Python/Zope Consulting and Support ... http://www.egenix.com/ mxODBC.Zope.Database.Adapter ... http://zope.egenix.com/ mxODBC, mxDateTime, mxTextTools ... http://python.egenix.com/
::: Try our new mxODBC.Connect Python Database Interface for free ! :::: eGenix.com Software, Skills and Services GmbH Pastor-Loeh-Str.48 D-40764 Langenfeld, Germany. CEO Dipl.-Math. Marc-Andre Lemburg Registered at Amtsgericht Duesseldorf: HRB 46611 http://www.egenix.com/company/contact/
On Mon, Mar 7, 2011 at 9:18 AM, M.-A. Lemburg
"Martin v. Löwis" wrote:
if anybody would *not* want to have a "Documentation" link automatically generated that points to packages.python.org/<project>, please speak up.
That would only make sense if there's something uploaded to the PyPI docs dir.
If PyPI can detect that, +1. Otherwise, I think it's better not adding such an automatic link, since no link is better than one going nowhere.
Absolutely - it only generates the link if there's something to link to (that is, there's been a documentation upload with an index.html file at the root, or in a top-level "html" directory). Richard
Richard Jones wrote:
On Mon, Mar 7, 2011 at 9:18 AM, M.-A. Lemburg
wrote: "Martin v. Löwis" wrote:
if anybody would *not* want to have a "Documentation" link automatically generated that points to packages.python.org/<project>, please speak up.
That would only make sense if there's something uploaded to the PyPI docs dir.
If PyPI can detect that, +1. Otherwise, I think it's better not adding such an automatic link, since no link is better than one going nowhere.
Absolutely - it only generates the link if there's something to link to (that is, there's been a documentation upload with an index.html file at the root, or in a top-level "html" directory).
I suggest: - Generate a link if there is documentation - Generate the text "No documentation" in the place where the link would be if there is no documentation. I have two reasons for suggesting this: 1. I'm thinking explicit is better than implicit here. The link for the documentation should always be in the same place on the page, so having a placeholder stating "there's nothing here" will make the page easier to read. You don't wonder if you missed it, or if something is wrong that the link disappeared -- it says right there what you want to know. 2. It might remind developers that it is possible to upload documentation with their package. Currently, a lot of stuff on pypi has poor or nonexistent documentation; the resource as a whole would be far more valuable if every package had at least a minimal summary of what it does and how to use it. (Even if someone has no need for your package, you still help them if they can determine that _quickly_.)
- Generate the text "No documentation" in the place where the link would be if there is no documentation.
-1. Saying "No documentation" would be wrong if the package, in fact, does have documentation, but elsewhere. Regards, Martin
On 3/7/2011 4:26 PM, "Martin v. Löwis" wrote:
- Generate the text "No documentation" in the place where the link would be if there is no documentation.
-1. Saying "No documentation" would be wrong if the package, in fact, does have documentation, but elsewhere.
"No documentation uploaded to PyPi", maybe? I can see some value in noting that it's possible, just not done for this release.
On Tue, Mar 8, 2011 at 8:06 AM, Mark Sienkiewicz
I suggest:
- Generate a link if there is documentation
Right, we do this already.
- Generate the text "No documentation" in the place where the link would be if there is no documentation.
I don't like this. The documentation space on pypi is offered as a space for projects that's convenient or where they otherwise wouldn't be able to host their own documentation website. It's not something I wish to force people to use (just like package upload isn't something we force people to do), and stating "no documentation" would be a bit of a lie in a bunch of cases. Even with additional clarifying wording it's still a negative statement that I don't think we need to make. Richard
On Mon, Mar 7, 2011 at 5:52 PM, Richard Jones
On Tue, Mar 8, 2011 at 8:06 AM, Mark Sienkiewicz
wrote: I suggest:
- Generate a link if there is documentation
Right, we do this already.
- Generate the text "No documentation" in the place where the link would be if there is no documentation.
I don't like this. The documentation space on pypi is offered as a space for projects that's convenient or where they otherwise wouldn't be able to host their own documentation website. It's not something I wish to force people to use (just like package upload isn't something we force people to do), and stating "no documentation" would be a bit of a lie in a bunch of cases. Even with additional clarifying wording it's still a negative statement that I don't think we need to make.
What about this: 1) have some sort of "disabled" link placeholder so the documentation link is always there, but not an attractive nuisance leading to a dead end when there are no docs available and 2) let project owners provide an alternative target for the link if they host their documentation elsewhere. -- Benji York
if anybody would *not* want to have a "Documentation" link automatically generated that points to packages.python.org/<project>, please speak up.
That would only make sense if there's something uploaded to the PyPI docs dir.
If PyPI can detect that, +1.
Yes, the link would certainly be conditional. Regards, Martin
"Martin v. Löwis" wrote:
if anybody would *not* want to have a "Documentation" link automatically generated that points to packages.python.org/<project>, please speak up.
That would only make sense if there's something uploaded to the PyPI docs dir.
If PyPI can detect that, +1.
Yes, the link would certainly be conditional.
Great. Thanks. -- Marc-Andre Lemburg eGenix.com Professional Python Services directly from the Source (#1, Mar 07 2011)
Python/Zope Consulting and Support ... http://www.egenix.com/ mxODBC.Zope.Database.Adapter ... http://zope.egenix.com/ mxODBC, mxDateTime, mxTextTools ... http://python.egenix.com/
::: Try our new mxODBC.Connect Python Database Interface for free ! :::: eGenix.com Software, Skills and Services GmbH Pastor-Loeh-Str.48 D-40764 Langenfeld, Germany. CEO Dipl.-Math. Marc-Andre Lemburg Registered at Amtsgericht Duesseldorf: HRB 46611 http://www.egenix.com/company/contact/
2011/3/6 "Martin v. Löwis"
What particular clause strikes you as particularly unfriendly?
Please understand that it may sound harsh, but is necessary - better be safe than sorry.
Nothing wrong about the warning itself, but about landing on a plain condensed text page. I think we should make it a html page. And maybe display the last ten packages doc updates ?
It actually *is* a html page (and always was). It just doesn't use any styling.
As for changing the style: please submit a html file to replace what is there (I refuse to do any styling . As for displaying the last ten doc updates: either submit a tracker request, or provide a patch.
Since "packages.python.org" allow us to have a directory with HTML
files, those could be made accessible under:
http://pypi.python.org/pypi/distribute/docs, with a big link on the top of http://pypi.python.org/pypi/distribute to go there.
[I wonder why "links" and "buttons" always have to be "big", and often "red" :-]
See my response to Lennart for the former: distribute/docs would be the "docs" release of "distribute". As for a big link: if you think your page should have one, you are free to make it yourself already.
http://packages.python.org/PROJECT/ would become
http://pypi.python.org/pypi/PROJECT/doc
IOW, not changes but just avoiding two places -- without giving any hint on each place about the existence of the other place.
Why Distribute would have two root pages ?
See above: what you propose cannot work. Also, I don't think many users care about the URLs of things. If your package home page is pypi/distribute, that's perfectly fine. Put a documentation link on that page, and be done.
Then, maybe http://pypi.python.org/pypi could simply become
http://packages.python.org, with:
- http://packages.python.org/PROJECT - http://packages.python.org/PROJECT/docs - http://packages.python.org/PROJECT/1.2 - etc..
That would break existing packages URLs, so -1. You cannot lightly change URLs in the Web - replacing an existing URL is a multi-year project.
Sigh... Could everyone please be more careful before they create URLs that will have to be maintained for YEARS? This is so frustrating. As a practical solution now: Which links are being broken? If someone goes into http://packages.python.org/PROJECT expecting documentation, and then he gets a general page for the project which links to the documentation, then I think it's not that bad. If someone's following a deep link into the documentation, we can give a 404 page which suggests adding a `/docs`, so people will slowly learn to update their links.
Individual package maintainers may do, but we still get lots of hits on cheeseshop.python.org, so that needs to be supported many years in the future. I'm not looking forward to having a *second* transitional URL.
Regards, Martin _______________________________________________ Distutils-SIG maillist - Distutils-SIG@python.org http://mail.python.org/mailman/listinfo/distutils-sig
-- Sincerely, Ram Rachum
Le 06/03/2011 22:17, "Martin v. Löwis" a écrit :
As for changing the style: please submit a html file to replace what is there (I refuse to do any styling .
Do you mean you don’t want to work on styling personally or that you object to someone proposing a patch adding styling? It it’s the latter, could you explain why? Regards
Am 07.03.2011 11:18, schrieb Éric Araujo:
Le 06/03/2011 22:17, "Martin v. Löwis" a écrit :
As for changing the style: please submit a html file to replace what is there (I refuse to do any styling .
Do you mean you don’t want to work on styling personally or that you object to someone proposing a patch adding styling?
The former. Consequentially, I accept any style changes that people propose without discussion (if they are spelled out explicitly, preferably as code). Regards, Martin
http://pypi.python.org/pypi/distribute/docs, with a big link on the top of http://pypi.python.org/pypi/distribute to go there.
I have now added a link at the top. Such a link already was there at the bottom, but now it's duplicated at the top also. Not sure whether it's big enough :-) Regards, Martin
It's Perfect thanks
2011/3/11 "Martin v. Löwis"
http://pypi.python.org/pypi/distribute/docs, with a big link on the top of http://pypi.python.org/pypi/distribute to go there.
I have now added a link at the top. Such a link already was there at the bottom, but now it's duplicated at the top also. Not sure whether it's big enough :-)
Regards, Martin
-- Tarek Ziadé | http://ziade.org
participants (10)
-
"Martin v. Löwis"
-
Benji York
-
cool-RR
-
Eric Smith
-
Lennart Regebro
-
M.-A. Lemburg
-
Mark Sienkiewicz
-
Richard Jones
-
Tarek Ziadé
-
Éric Araujo