On Wed, Jan 15, 2014 at 1:30 AM, Nick Coghlan <ncoghlan@gmail.com> wrote:

On 15 Jan 2014 17:15, "Marcus Smith" <qwcode@gmail.com> wrote:

...

Fyi, the "Python Packaging User Guide" has moved from bitbucket to github.

The new project home is here: https://github.com/pypa/python-packaging-user-guide and the built site is still here: https://python-packaging-user-guide.readthedocs.org/en/latest/

Guess I better make a new clone :)

...

For those who are interested in helping, a quick survey of the text will show many sections marked up with "FIXME" comments. Although general editing is helpful, I think we mostly need "packaging experts" at this point who are willing to invest the time in filling out and correcting the sections they feel strong on.

As stated in the README, "The guide is part of a larger effort to improve all of the packaging and installation docs, including pip, setuptools, virtualenv, and wheel. Ultimately, users need more than a "guide" to feel confident about the current tools. They need complete, accurate and inter-consistent documentation across all the projects"

I would include docs.python.org in that list. I've already added links from the relevant pages to the user's guide (as even in its current incomplete state it is a better end user resource than the stdlib docs), but ultimately we need to cull the current outdated information from the stdlib docs and actively promote the development of cross-version compatible packages.

Is there a description somewhere of the plan for what packaging-related information will be covered in docs.python.org proper (and the stages for getting there), and which information will be off-loaded to the documentation for the other projects that Marcus mentioned? Will there be any planned overlap? I seem to remember or got the impression from earlier e-mails on the Distutils list that a lot of the information currently in docs.python.org was going to be removed at some point. (Some of it still seems useful by the way, for example by covering things that are still stubs in the PPUG. Also by the way, is that the right acronym for quick reference? :) ). --Chris

On 16 January 2014 01:25, Chris Jerdonek <chris.jerdonek@gmail.com> wrote:

Is there a description somewhere of the plan for what packaging-related information will be covered in docs.python.org proper (and the stages for getting there), and which information will be off-loaded to the documentation for the other projects that Marcus mentioned?

I don't have a clear picture of the split myself but it seems to me that docs.python.org should be the master reference data for *distutils*. That's somewhat screwed, though, as we're recommending use of setuptools, and setuptools messes round so invasively with distutils that the usefulness of pure distutils documentation is limited :-( I still think that the best resource available would be a basic "best practice" project template for a simple pure-python package with a few tests. I started putting one together myself (https://github.com/pfmoore/sampleproject). It's basically done, but I'm not sure how it (or something like it) could be incorporated into the docs. At the moment, I tend to use it as a cut-and-paste starting point, and I suspect that most people have something similar. Also, it makes me a bit sad how complicated the setup.py ended up looking (given that it was supposed to be a "minimum starting point" example... Maybe if pip gets support for plugin commands, I could write a "pip new-project" command that generates an empty project template. That might be a good place for it - although it takes pip away from being a pure package management tool and into more of a project development tool, which maybe isn't right. I'd rather not add yet another tool to my "essential staring point for building a project" toolset, though... Paul

On 16 January 2014 09:40, Nick Coghlan <ncoghlan@gmail.com> wrote:

Audrey Roy's "cookiecutter" project is just such a tool (although her default config is far from minimal - setup.py, GitHub, ReadTheDocs, tox, Travis, documentation skeleton, etc. It's all reasonable recommendations, though)

Agreed, I was pointed to that at one point. For me, it suffers from the problem of being yet another tool, as well as the default template available being very complex, as you said. But yes, it looks useful for more complex projects. I do think the PUG needs a "this is how you start" basic template though, that includes good practices like the right classifiers, using entry points for scripts, basic unit tests, a readme etc. The current guide doesn't even have a "Basic Project Template" section in the index :-( I'll try to find some time to add one. On that note, the PUG index currently feels a little overwhelming from the point of view of someone who just wants to get a job done. it's got a lot of "Getting started with X" and "What is" sections, but nothing like "Installing a package from PyPI" or "Starting a new project". Maybe the index should be reorganised to be more task-oriented, and less concerned with providing history and background to the confusion that led us to where we are now? I'd be tempted to actually remove a lot of what's currently in the contents, and relegate it to some sort of "background" section (which would probably need to be organised into subsections of its own, but that level of detail doesn't need to be on the front page). Paul

On Jan 16, 2014, at 9:20 AM, Daniel Holth <dholth@gmail.com> wrote:

Has anyone ever written a setup.py that was *not* copy-and-pasted from somewhere else?

On Thu, Jan 16, 2014 at 5:17 AM, Paul Moore <p.f.moore@gmail.com> wrote:

...

On 16 January 2014 09:40, Nick Coghlan <ncoghlan@gmail.com> wrote:

...

Audrey Roy's "cookiecutter" project is just such a tool (although her default config is far from minimal - setup.py, GitHub, ReadTheDocs, tox, Travis, documentation skeleton, etc. It's all reasonable recommendations, though)

Agreed, I was pointed to that at one point. For me, it suffers from the problem of being yet another tool, as well as the default template available being very complex, as you said. But yes, it looks useful for more complex projects.

I do think the PUG needs a "this is how you start" basic template though, that includes good practices like the right classifiers, using entry points for scripts, basic unit tests, a readme etc. The current guide doesn't even have a "Basic Project Template" section in the index :-( I'll try to find some time to add one.

On that note, the PUG index currently feels a little overwhelming from the point of view of someone who just wants to get a job done. it's got a lot of "Getting started with X" and "What is" sections, but nothing like "Installing a package from PyPI" or "Starting a new project". Maybe the index should be reorganised to be more task-oriented, and less concerned with providing history and background to the confusion that led us to where we are now? I'd be tempted to actually remove a lot of what's currently in the contents, and relegate it to some sort of "background" section (which would probably need to be organised into subsections of its own, but that level of detail doesn't need to be on the front page).

Paul

I write my setup.py’s from scratch :D ----------------- Donald Stufft PGP: 0x6E3CBCE93372DCFA // 7C6B 7C5D 5E2B 6356 A926 F04F 6E3C BCE9 3372 DCFA

On that note, the PUG index currently feels a little overwhelming

The main index is 2 levels deep currently. Let me drop it to one level and see how that looks. I personally like a deep index as my main entry point to docs, but I can see it being a bit much.

the point of view of someone who just wants to get a job done. it's got a lot of "Getting started with X" and "What is" sections, but nothing like "Installing a package from PyPI" or "Starting a new project". Maybe the index should be reorganised to be more task-oriented, and less concerned with providing history and background to the confusion that led us to where we are now?

2 things: 1) In my opinion, a big part of the PUG is about "deconfusing" people, and giving confidence that there's consensus on what to do now (with a justification), and there's plans to move forward. That's what many people need and will come to the PUG for. They already know the basics of pip and setuptools. 2) As for providing basic pip/setuptools tutorials, I've taken the position that the PUG shouldn't do it, but instead defer with links. The project docs themselves should have tutorials, so let's just do it once, and right, and link to it. Supposing you still thought it was a good idea for both to maintain tutorials, practically speaking, I think it will fail. One, or both will end up being not maintained or inconsistent with each other in the long run. I want to construct something that has a good chance of persisting and staying up to date. We have access to the 4 main projects, and can get PRs through. There seems to be an unspoken idea that we can't update the setuptools docs. We rely on setuptools heavily, and it has years of life left in it. The docs can be first rate, and consistent with what's currently going on. But in saying that, I'm still open to other TOC ideas. It is an open project. But with any idea, I'd like to see a full breakdown of the alternative TOC and how it covers everything we have now.

I still think that the best resource available would be a basic "best practice" project template for a simple pure-python package with a few tests. I started putting one together myself (https://github.com/pfmoore/sampleproject). It's basically done, but I'm not sure how it (or something like it) could be incorporated into the docs.

I like this idea. how about move it to the "pypa" org to make it more official, and then it can be mentioned here: https://python-packaging-user-guide.readthedocs.org/en/latest/packaging.html...

On 16 January 2014 15:14, Paul Moore <p.f.moore@gmail.com> wrote:

I'm happy to do that, if people think it's sufficiently representative of "best practice" (and if they don't, they can always improve it :-))

Done.

I don't have a clear picture of the split myself but it seems to me that docs.python.org should be the master reference data for *distutils*. That's somewhat screwed, though, as we're recommending use of setuptools, and setuptools messes round so invasively with distutils that the usefulness of pure distutils documentation is limited :-(

docs.python.org should provide a distutils reference, and drop the "Installing/Distributing Python Modules" guides in deference to the PUG. and setuptools (as an extension of distutils) should provide a *complete* index of commands/options that covers everything, not just what it changed or added, because it's too hard for users to keep track of what's pure vs modified. That's my plan in the refactor of the setuptools docs I'm working on.

ok, let's do distutils-sig. true, it is a pypa project, but non-pypa people are already in this thread, and I imagine all pypa-dev people are on distutils-sig. On Thu, Jan 16, 2014 at 9:49 AM, Carl Meyer <carl@oddbird.net> wrote:

Could we stop cross-posting this thread to both pypa-dev and distutils-sig? Seems like it belongs on pypa-dev to me, but I don't really care so long as it isn't cross-posted to both :-)

Carl _______________________________________________ Distutils-SIG maillist - Distutils-SIG@python.org https://mail.python.org/mailman/listinfo/distutils-sig

On 16 January 2014 17:46, Marcus Smith <qwcode@gmail.com> wrote:

...

I don't have a clear picture of the split myself but it seems to me that docs.python.org should be the master reference data for *distutils*. That's somewhat screwed, though, as we're recommending use of setuptools, and setuptools messes round so invasively with distutils that the usefulness of pure distutils documentation is limited :-(

docs.python.org should provide a distutils reference, and drop the "Installing/Distributing Python Modules" guides in deference to the PUG. and setuptools (as an extension of distutils) should provide a *complete* index of commands/options that covers everything, not just what it changed or added, because it's too hard for users to keep track of what's pure vs modified. That's my plan in the refactor of the setuptools docs I'm working on.

That makes sense. But I think it's a case of getting people to what they need as quickly as possible (and having the details available further on, if they need them). The pip documentation is great for this. Go to the front page, first thing you see is "Quickstart". First thing that hits your eye on that page is "pip install SomePackage==1.0". Maybe that's what the PUG should have - the very first index entry is "Quick Start". That points to a page that goes: Installing a package ============== Use `pip` to install from `PyPI`: pip install SomePackage Creating a project ============= Install `pip`, `setuptools` and `wheel`. [Question: In the system python? Introduce virtualenv here?] Create a project structure like this:: myproject myproject __init__.py setup.py setup.cfg tests README.txt `Here` is a basic setup.py you can copy and edit. ... etc. (Not too long, but cover the essentials). In the above, I'm using `...` to mark links to the detailed documentation. After that "Quick Start" link, the rest of the index can go into the details however people prefer. It's just that quick start that needs to be up front. Maybe I can do a PR for this - would that be useful? I'm lousy at writing documentation, but if I put a shell in that people can work from would that help? Paul

On 16 January 2014 18:39, Marcus Smith <qwcode@gmail.com> wrote:

given my previous arguments, if we have a "Quickstart", I would just have it contain links to the pip & setuptools quickstarts (and wheel too I guess).

Yeah... Although I question the value of setting up a chain of 3 links to get someone to a pip one-liner. That seems to me to be taking DRY too far. Can't we at least put the basic "pip install" into the PUG? Here's an example of what I was meaning (please excuse the fact that I know nearly nothing about restructured text, and completely nothing about Sphinx...): https://github.com/pfmoore/python-packaging-user-guide/tree/quickstart Paul

fair question. partly due to personal comfort level with git/github, but also was hoping we'd get more involvement using github, since it's more popular.

Your choice, of course, and I understand about the personal preference part. I do wonder how much involvement you will get from people who would be put off getting involved by the fact that a project is on BitBucket (which fully supports Git as well as Mercurial). There's so little difference in functionality between the two sites that I can't see any barrier to a real contributor (real = someone willing to spend a reasonable amount of time on a project, larger than the time required to learn a new but similar site). I suppose time will tell :-) Regards, Vinay Sajip

It's not just part of a joint PSU / PYPA plan to go "full Rackspace"? :-) On Wed, Jan 15, 2014 at 2:53 PM, Donald Stufft <donald@stufft.io> wrote:

On Jan 15, 2014, at 2:27 PM, Vinay Sajip <vinay_sajip@yahoo.co.uk> wrote:

...

...

fair question. partly due to personal comfort level with git/github, but also was hoping we'd get more involvement using github, since it's more popular.

Your choice, of course, and I understand about the personal preference part. I do wonder how much involvement you will get from people who would be put off getting involved by the fact that a project is on BitBucket (which fully supports Git as well as Mercurial). There's so little difference in functionality between the two sites that I can't see any barrier to a real contributor (real = someone willing to spend a reasonable amount of time on a project, larger than the time required to learn a new but similar site). I suppose time will tell :-)

Regards,

Vinay Sajip

Not that I won’t contribute to something on bitbucket, but it factors into my decision and I’m less likely to contribute to something on bitbucket, and even more less likely to contribute to something self hosted or on another host.

----------------- Donald Stufft PGP: 0x6E3CBCE93372DCFA // 7C6B 7C5D 5E2B 6356 A926 F04F 6E3C BCE9 3372 DCFA