Another conversation starter - pip documentation in the Python docs
I don't think there is any doubt that we need to document to at least some extent how to use pip, in the Python documentation for 3.4. The obvious place is "Installing Python Modules" as a chapter to itself. What is less clear to me is how much to document - just basic "pip install XXX", or the whole pip command set, or somewhere in between? Should there be some type of "refer to www.pip-installer.org for the complete documentation" reference? Paul.
On 14 July 2013 21:09, Paul Moore <p.f.moore@gmail.com> wrote:
I don't think there is any doubt that we need to document to at least some extent how to use pip, in the Python documentation for 3.4. The obvious place is "Installing Python Modules" as a chapter to itself.
What is less clear to me is how much to document - just basic "pip install XXX", or the whole pip command set, or somewhere in between? Should there be some type of "refer to www.pip-installer.org for the complete documentation" reference?
This is the hole https://python-packaging-user-guide.readthedocs.org/en/latest/ is supposed to fill - once it's "ready" (i.e. things have stabilised sufficiently , then I'd like to replace the "Installing Python Modules" and "Distributing Python Modules" sections for 2.7 and 3.3 with some *very* abbreviated quick start guides that then reference that site. The 3.3 changes would then carry over into 3.4. I spent some time at PyCon AU talking to Matthew Iverson ( https://bitbucket.org/Ivoz/python-packaging-user-guide) who I believe Marcus was hoping to get back to that after pip 1.4 was out the door, but anyone on the PyPA list on BitBucket actually has full access to accept pull requests, etc. Cheers, Nick. -- Nick Coghlan | ncoghlan@gmail.com | Brisbane, Australia
On 14 July 2013 12:42, Nick Coghlan <ncoghlan@gmail.com> wrote:
This is the hole https://python-packaging-user-guide.readthedocs.org/en/latest/ is supposed to fill - once it's "ready" (i.e. things have stabilised sufficiently , then I'd like to replace the "Installing Python Modules" and "Distributing Python Modules" sections for 2.7 and 3.3 with some *very* abbreviated quick start guides that then reference that site. The 3.3 changes would then carry over into 3.4.
Hmm, OK. I've no problem with that (although I do find the packaging guide pretty hard to get into for an end user who only wants to *use* packages, not *create* them, but that's a separate issue for me to address by providing some pull requests). I was more thinking in terms of your quick start guides. I think we should explain *in the core documentation* how to (a) install a new package, (b) uninstall a package, (c) list what is installed and (d) upgrade pip itself. That translates to the pip install, uninstall, and list commands at a minimum. I could offer some text, if that's the way you want to go with this. How about if I provide a new (short) document called something like "Python package management" and we work out how to integrate it into the docs as things settle down? Paul
On 14 July 2013 23:01, Paul Moore <p.f.moore@gmail.com> wrote:
On 14 July 2013 12:42, Nick Coghlan <ncoghlan@gmail.com> wrote:
This is the hole https://python-packaging-user-guide.readthedocs.org/en/latest/ is supposed to fill - once it's "ready" (i.e. things have stabilised sufficiently , then I'd like to replace the "Installing Python Modules" and "Distributing Python Modules" sections for 2.7 and 3.3 with some *very* abbreviated quick start guides that then reference that site. The 3.3 changes would then carry over into 3.4.
Hmm, OK. I've no problem with that (although I do find the packaging guide pretty hard to get into for an end user who only wants to *use* packages, not *create* them, but that's a separate issue for me to address by providing some pull requests). I was more thinking in terms of your quick start guides. I think we should explain *in the core documentation* how to (a) install a new package, (b) uninstall a package, (c) list what is installed and (d) upgrade pip itself. That translates to the pip install, uninstall, and list commands at a minimum.
I could offer some text, if that's the way you want to go with this. How about if I provide a new (short) document called something like "Python package management" and we work out how to integrate it into the docs as things settle down?
That sounds great - so far it's mostly just been myself and Marcus thinking about it (mostly Marcus, to be honest, along with a couple of folks that submitted pull requests and BitBucket issues), and it keeps getting bumped down the todo list by other things. I think we're getting closer to having something stable enough to document clearly, though - with distribute merged back into setuptools and pip not far away, the bootstrapping seems to be the only remaining slightly messy part (since the 3.4 discussions aren't relevant to the user guide as yet). As far as your first point goes, I agree the "Installation Tutorial" part should probably come first and definitely needs more content. I did just accept a pull request earlier that at least makes that page more than just a list of headings (see https://python-packaging-user-guide.readthedocs.org/en/latest/installation_t... courtesy of https://bitbucket.org/alexjeffburke) Cheers, Nick. -- Nick Coghlan | ncoghlan@gmail.com | Brisbane, Australia
Hmm, OK. I've no problem with that (although I do find the packaging guide pretty hard to get into for an end user who only wants to *use* packages, not *create* them
there's a section marked "Installation Tutorial". Someone wanting to install packages should be able to get into that, once it actually has content : )
I think we should explain *in the core documentation*
How about if I provide a new (short) document called something like "Python
package management"
IMO, we should put the energy into one comprehensive document (the new user guide) and link out to it, not duplicate effort into the core docs. The "Installing Python Modules"/"Distributing Python Modules" documents should be integrated into the new User Guide. It will be confusing and anti-zen for a user to come upon those documents and have to reconcile it with the user guide Marcus
On 14 July 2013 18:02, Marcus Smith <qwcode@gmail.com> wrote:
there's a section marked "Installation Tutorial". Someone wanting to install packages should be able to get into that, once it actually has content : )
Yes, I see that. I'm not sure I like the up-front "decide between user or system or virtualenv" presentation, though. I'm working on something I prefer, see what you think when it's done. My perspective is that someone who's used to writing Python code wants to install requests (and get on with his latest script). How does he do that? He doesn't want to be presented with decisions to make, he just wants to know how to do it. "pip install --user requests" is the answer he is looking for, frankly. (Missing out --user gets permission issues to deal with, and virtualenvs are more than he's looking to deal with at the moment). The guide should get this person to that command as quickly as possible. I think we should explain *in the core documentation*
How about if I provide a new (short) document called something like
"Python package management"
IMO, we should put the energy into one comprehensive document (the new user guide) and link out to it, not duplicate effort into the core docs.
OK... But remember that most users are consumers of packages, not creators of them. The packaging guide should reflect that with "install and maintain packages" on page 1, and creating packages squarely in "advanced" usage. Is that in line with the goals of the packaging guide? (If not, let's just get a user-only starter page in the Python docs and leave the packaging guide as the "more comprehensive" documentation it can refer to). Paul
On 14 July 2013 18:02, Marcus Smith <qwcode@gmail.com> wrote:
there's a section marked "Installation Tutorial". Someone wanting to install packages should be able to get into that, once it actually has content : )
Yes, I see that. I'm not sure I like the up-front "decide between user or system or virtualenv" presentation, though. I'm working on something I prefer, see what you think when it's done.
yea, don't take the current install tutorial TOC that seriously. The user/global/virtualenv content came from a recent merge Nick referred to above. We just need knowledgeable people to get in there and start working/changing OK... But remember that most users are consumers of packages, not creators
of them. The packaging guide should reflect that
Like Nick said, we can put the "Installation Tutorial" above the "Packaging Tutorial". Neither tutorial should be considered "Advanced" IMO. The tutorials should be crisp and fast. Also, we *could* put a "Quickstart" above both tutorials, that just lists the frequent commands with one-liner descriptions, but we have to be really careful that it doesn't end up duping the tutorials, which are also intended to be quick as well.
If not, let's just get a user-only starter page in the Python docs and leave the packaging guide as the "more comprehensive" documentation it can refer to).
anything that results in feeling like the user guide needs a "user-only starter page in Python docs" means we're doing it wrong IMO : ) I admit the title itself concerns me: "Python Packaging User Guide", like it should have the word "Installation" in it. "Python Installation and Packaging User Guide"? (its soooo long though....) Marcus
I admit the title itself concerns me: "Python Packaging User Guide", like it should have the word "Installation" in it. "Python Installation and Packaging User Guide"? (its soooo long though....)
other ideas: "Python Installation and Packaging Guide" "Python Installation and Distribution Guide"
On 14 July 2013 18:49, Marcus Smith <qwcode@gmail.com> wrote:
I admit the title itself concerns me: "Python Packaging User Guide", like it should have the word "Installation" in it. "Python Installation and Packaging User Guide"? (its soooo long though....)
I like "Package Management Guide". Strong hints of managing existing 3rd party packages, which is good because it's what the majority want, but general enough to allow for including managing the build & distribution of your own packages. BTW, I'm sick and tired of agonising every time I use the word "package" over whether I should be "correct" and use "distribution". Can the guide just come right out and bless the occasionally-ambiguous but commonly-used dual nature of the word "package"? If not, can people start actually *using* "distribution" consistently for what pip downloads and installs, so I can find a few more examples for me to copy when I end up with awkward phrases like "distributing your distribution"...? (You'd never believe English was my native language, would you? :-)) Paul
BTW, I'm sick and tired of agonising every time I use the word "package" over whether I should be "correct" and use "distribution". Can the guide just come right out and bless the occasionally-ambiguous but commonly-used dual nature of the word "package"? If not, can people start actually *using* "distribution" consistently for what pip downloads and installs, so I can find a few more examples for me to copy when I end up with awkward phrases like "distributing your distribution"...? (You'd never believe English was my native language, would you? :-))
I hear you. I feel the same agony. It think we should use the word "Distribution", but it's hard to compete when PyPI uses "Package". Nick, what do we do? : ) Marcus
Donald: thoughts on changing our use of "Package" on pypi to "Distribution"? (except for the title of course) If we're not going to do that, we should explain and bless the double use of "Package" and drop using "Distribution" in any docs. Our fundamental concepts shouldn't be confusing and conflicted. On Sun, Jul 14, 2013 at 1:05 PM, Marcus Smith <qwcode@gmail.com> wrote:
BTW, I'm sick and tired of agonising every time I use the word "package" over whether I should be "correct" and use "distribution". Can the guide just come right out and bless the occasionally-ambiguous but commonly-used dual nature of the word "package"? If not, can people start actually *using* "distribution" consistently for what pip downloads and installs, so I can find a few more examples for me to copy when I end up with awkward phrases like "distributing your distribution"...? (You'd never believe English was my native language, would you? :-))
I hear you. I feel the same agony. It think we should use the word "Distribution", but it's hard to compete when PyPI uses "Package". Nick, what do we do? : )
Marcus
On Jul 14, 2013, at 5:22 PM, Marcus Smith <qwcode@gmail.com> wrote:
Donald: thoughts on changing our use of "Package" on pypi to "Distribution"? (except for the title of course) If we're not going to do that, we should explain and bless the double use of "Package" and drop using "Distribution" in any docs. Our fundamental concepts shouldn't be confusing and conflicted.
On Sun, Jul 14, 2013 at 1:05 PM, Marcus Smith <qwcode@gmail.com> wrote:
BTW, I'm sick and tired of agonising every time I use the word "package" over whether I should be "correct" and use "distribution". Can the guide just come right out and bless the occasionally-ambiguous but commonly-used dual nature of the word "package"? If not, can people start actually *using* "distribution" consistently for what pip downloads and installs, so I can find a few more examples for me to copy when I end up with awkward phrases like "distributing your distribution"...? (You'd never believe English was my native language, would you? :-))
I hear you. I feel the same agony. It think we should use the word "Distribution", but it's hard to compete when PyPI uses "Package". Nick, what do we do? : )
Marcus
_______________________________________________ Distutils-SIG maillist - Distutils-SIG@python.org http://mail.python.org/mailman/listinfo/distutils-sig
PyPI will eventually move to using the definitions as defined in PEP426 http://www.python.org/dev/peps/pep-0426/#supporting-definitions . ----------------- Donald Stufft PGP: 0x6E3CBCE93372DCFA // 7C6B 7C5D 5E2B 6356 A926 F04F 6E3C BCE9 3372 DCFA
no reason not to change "Package" to "Distribution" now, right? this (http://docs.python.org/2/install/index.html) already uses the "Distribution" word. which means changing sentences like "There are currently 32660 packages here." to "There are currently 32660 distributions here." and the main table listing would use the word "Distribution" On Sun, Jul 14, 2013 at 2:24 PM, Donald Stufft <donald@stufft.io> wrote:
On Jul 14, 2013, at 5:22 PM, Marcus Smith <qwcode@gmail.com> wrote:
Donald: thoughts on changing our use of "Package" on pypi to "Distribution"? (except for the title of course) If we're not going to do that, we should explain and bless the double use of "Package" and drop using "Distribution" in any docs. Our fundamental concepts shouldn't be confusing and conflicted.
On Sun, Jul 14, 2013 at 1:05 PM, Marcus Smith <qwcode@gmail.com> wrote:
BTW, I'm sick and tired of agonising every time I use the word "package" over whether I should be "correct" and use "distribution". Can the guide just come right out and bless the occasionally-ambiguous but commonly-used dual nature of the word "package"? If not, can people start actually *using* "distribution" consistently for what pip downloads and installs, so I can find a few more examples for me to copy when I end up with awkward phrases like "distributing your distribution"...? (You'd never believe English was my native language, would you? :-))
I hear you. I feel the same agony. It think we should use the word "Distribution", but it's hard to compete when PyPI uses "Package". Nick, what do we do? : )
Marcus
_______________________________________________ Distutils-SIG maillist - Distutils-SIG@python.org http://mail.python.org/mailman/listinfo/distutils-sig
PyPI will eventually move to using the definitions as defined in PEP426 http://www.python.org/dev/peps/pep-0426/#supporting-definitions .
----------------- Donald Stufft PGP: 0x6E3CBCE93372DCFA // 7C6B 7C5D 5E2B 6356 A926 F04F 6E3C BCE9 3372 DCFA
On Jul 14, 2013, at 5:29 PM, Marcus Smith <qwcode@gmail.com> wrote:
no reason not to change "Package" to "Distribution" now, right? this (http://docs.python.org/2/install/index.html) already uses the "Distribution" word. which means changing sentences like "There are currently 32660 packages here." to "There are currently 32660 distributions here." and the main table listing would use the word "Distribution"
That's 32600 projects, There are almost 200k distributions. And the main table listing would be "Releases" or "Project Releases".
On Sun, Jul 14, 2013 at 2:24 PM, Donald Stufft <donald@stufft.io> wrote:
On Jul 14, 2013, at 5:22 PM, Marcus Smith <qwcode@gmail.com> wrote:
Donald: thoughts on changing our use of "Package" on pypi to "Distribution"? (except for the title of course) If we're not going to do that, we should explain and bless the double use of "Package" and drop using "Distribution" in any docs. Our fundamental concepts shouldn't be confusing and conflicted.
On Sun, Jul 14, 2013 at 1:05 PM, Marcus Smith <qwcode@gmail.com> wrote:
BTW, I'm sick and tired of agonising every time I use the word "package" over whether I should be "correct" and use "distribution". Can the guide just come right out and bless the occasionally-ambiguous but commonly-used dual nature of the word "package"? If not, can people start actually *using* "distribution" consistently for what pip downloads and installs, so I can find a few more examples for me to copy when I end up with awkward phrases like "distributing your distribution"...? (You'd never believe English was my native language, would you? :-))
I hear you. I feel the same agony. It think we should use the word "Distribution", but it's hard to compete when PyPI uses "Package". Nick, what do we do? : )
Marcus
_______________________________________________ Distutils-SIG maillist - Distutils-SIG@python.org http://mail.python.org/mailman/listinfo/distutils-sig
PyPI will eventually move to using the definitions as defined in PEP426 http://www.python.org/dev/peps/pep-0426/#supporting-definitions .
----------------- Donald Stufft PGP: 0x6E3CBCE93372DCFA // 7C6B 7C5D 5E2B 6356 A926 F04F 6E3C BCE9 3372 DCFA
----------------- Donald Stufft PGP: 0x6E3CBCE93372DCFA // 7C6B 7C5D 5E2B 6356 A926 F04F 6E3C BCE9 3372 DCFA
On 14 July 2013 22:36, Marcus Smith <qwcode@gmail.com> wrote:
That's 32600 projects, There are almost 200k distributions. And the main
table listing would be "Releases" or "Project Releases".
ok, got it. anything I do from here on will follow this.
That's much better. I apologise, I hadn't noticed that PEP 426 included terminology definitions. Paul
On 15 Jul 2013 07:45, "Paul Moore" <p.f.moore@gmail.com> wrote:
On 14 July 2013 22:36, Marcus Smith <qwcode@gmail.com> wrote:
That's 32600 projects, There are almost 200k distributions. And the
main table listing would be "Releases" or "Project Releases".
ok, got it. anything I do from here on will follow this.
That's much better. I apologise, I hadn't noticed that PEP 426 included terminology definitions.
They were necessary for me to keep them straight in my own head. The original set were a bit odd, but I think the project/release/distribution/archive split has ended up in a reasonable place after a few iterations (it's still open to revisions if anything seems too awkward, though). I don't think the ambiguity of "package" will ever go away entirely, but we can justify that to some degree by noting that distributions mainly serve to get Python packages and modules installed and available for import. Cheers, Nick.
Paul
_______________________________________________ Distutils-SIG maillist - Distutils-SIG@python.org http://mail.python.org/mailman/listinfo/distutils-sig
although some of the uses could be argued as needing "Project" e.g "Package documentation is hosted on its own domain" On Sun, Jul 14, 2013 at 2:29 PM, Marcus Smith <qwcode@gmail.com> wrote:
no reason not to change "Package" to "Distribution" now, right? this (http://docs.python.org/2/install/index.html) already uses the "Distribution" word. which means changing sentences like "There are currently 32660 packages here." to "There are currently 32660 distributions here." and the main table listing would use the word "Distribution"
On Sun, Jul 14, 2013 at 2:24 PM, Donald Stufft <donald@stufft.io> wrote:
On Jul 14, 2013, at 5:22 PM, Marcus Smith <qwcode@gmail.com> wrote:
Donald: thoughts on changing our use of "Package" on pypi to "Distribution"? (except for the title of course) If we're not going to do that, we should explain and bless the double use of "Package" and drop using "Distribution" in any docs. Our fundamental concepts shouldn't be confusing and conflicted.
On Sun, Jul 14, 2013 at 1:05 PM, Marcus Smith <qwcode@gmail.com> wrote:
BTW, I'm sick and tired of agonising every time I use the word "package" over whether I should be "correct" and use "distribution". Can the guide just come right out and bless the occasionally-ambiguous but commonly-used dual nature of the word "package"? If not, can people start actually *using* "distribution" consistently for what pip downloads and installs, so I can find a few more examples for me to copy when I end up with awkward phrases like "distributing your distribution"...? (You'd never believe English was my native language, would you? :-))
I hear you. I feel the same agony. It think we should use the word "Distribution", but it's hard to compete when PyPI uses "Package". Nick, what do we do? : )
Marcus
_______________________________________________ Distutils-SIG maillist - Distutils-SIG@python.org http://mail.python.org/mailman/listinfo/distutils-sig
PyPI will eventually move to using the definitions as defined in PEP426 http://www.python.org/dev/peps/pep-0426/#supporting-definitions .
----------------- Donald Stufft PGP: 0x6E3CBCE93372DCFA // 7C6B 7C5D 5E2B 6356 A926 F04F 6E3C BCE9 3372 DCFA
I believe Marcus was hoping to get back to that after pip 1.4 was out the door, but anyone on the PyPA list on BitBucket actually has full access to accept pull requests, etc.
yes, the time has come to get this thing going or risk getting a "yet another dead document" rep, which it's starting to get. Marcus
participants (4)
-
Donald Stufft -
Marcus Smith -
Nick Coghlan -
Paul Moore