From jkleint at gmail.com Fri Sep 25 01:15:22 2009 From: jkleint at gmail.com (John Kleint) Date: Thu, 24 Sep 2009 19:15:22 -0400 Subject: [Doc-SIG] Request for Eyeballs: Python Project Howto Message-ID: <6496ee60909241615g7d94d1bar68a3be14ec4598b9@mail.gmail.com> I'm writing an introduction to releasing open-source Python projects. Having recently gone through it for the first time myself, I was amazed at how far and wide I had to range to pull together all the information that goes into making a good Python package.? So I thought I'd write it up and share: http://infinitemonkeycorps.net/docs/pph/ It's tentatively called the "Python Project Howto," and it's aimed at people who, though not necessarily new to Python, may be new to packaging and possibly open source. It tries to be succinct and practical, demonstrating by example.? It covers choosing project hosting, setting up version control (Subversion basics), code quality (Pylint) and style (PEP 8), documentation (reStructuredText, Sphinx), unit testing (doctest and unittest), licensing, packaging (distutils), and release (PyPI). One thing I don't want it to be is an exhaustive list of all the possibilities for each of those areas.? For instance, I cover reStructuredText and Sphinx, but not epydoc; distutils but not setuptools. I've tried to pick the simplest, most common among several options, and sometimes provided a link to others (pip, nose). I'm trying to Keep It Simple for people just dipping their toes into the Python ecosystem.? I'd really like to know what people think; it would be great to get some feedback on it. Thanks! -John From fuzzyman at voidspace.org.uk Wed Sep 30 15:43:58 2009 From: fuzzyman at voidspace.org.uk (Michael Foord) Date: Wed, 30 Sep 2009 14:43:58 +0100 Subject: [Doc-SIG] Request for Eyeballs: Python Project Howto In-Reply-To: <6496ee60909241615g7d94d1bar68a3be14ec4598b9@mail.gmail.com> References: <6496ee60909241615g7d94d1bar68a3be14ec4598b9@mail.gmail.com> Message-ID: <4AC3609E.20008@voidspace.org.uk> John Kleint wrote: > I'm writing an introduction to releasing open-source Python projects. > Having recently gone through it for the first time myself, I was > amazed at how far and wide I had to range to pull together all the > information that goes into making a good Python package. So I thought > I'd write it up and share: > > http://infinitemonkeycorps.net/docs/pph/ > Just skimmed it so far (up to choosing a version control system). *Very* nice. Once it is complete you should talk to Andrew Kuchling about making it an official Python-HOWTO. You say you don't cover setuptools, but you do use easy_install... Once the work Tarek Ziade is doing is more complete, both on distutils and Distribute (setuptools replacement), it would be great to see the HOWTO updated to cover them. Anyway, I'll keep reading and come back with any more comments if I have any. All the best, Michael > It's tentatively called the "Python Project Howto," and it's aimed at > people who, though not necessarily new to Python, may be new to > packaging and possibly open source. It tries to be succinct and > practical, demonstrating by example. It covers choosing project > hosting, setting up version control (Subversion basics), code quality > (Pylint) and style (PEP 8), documentation (reStructuredText, Sphinx), > unit testing (doctest and unittest), licensing, packaging (distutils), > and release (PyPI). > > One thing I don't want it to be is an exhaustive list of all the > possibilities for each of those areas. For instance, I cover > reStructuredText and Sphinx, but not epydoc; distutils but not > setuptools. I've tried to pick the simplest, most common among > several options, and sometimes provided a link to others (pip, nose). > I'm trying to Keep It Simple for people just dipping their toes into > the Python ecosystem. I'd really like to know what people think; it > would be great to get some feedback on it. Thanks! > > -John > _______________________________________________ > Doc-SIG maillist - Doc-SIG at python.org > http://mail.python.org/mailman/listinfo/doc-sig > -- http://www.ironpythoninaction.com/ From fuzzyman at voidspace.org.uk Wed Sep 30 15:49:46 2009 From: fuzzyman at voidspace.org.uk (Michael Foord) Date: Wed, 30 Sep 2009 14:49:46 +0100 Subject: [Doc-SIG] Request for Eyeballs: Python Project Howto In-Reply-To: <6496ee60909241615g7d94d1bar68a3be14ec4598b9@mail.gmail.com> References: <6496ee60909241615g7d94d1bar68a3be14ec4598b9@mail.gmail.com> Message-ID: <4AC361FA.4090102@voidspace.org.uk> John Kleint wrote: > I'm writing an introduction to releasing open-source Python projects. > Having recently gone through it for the first time myself, I was > amazed at how far and wide I had to range to pull together all the > information that goes into making a good Python package. So I thought > I'd write it up and share: > > http://infinitemonkeycorps.net/docs/pph/ > Maybe move licensing to be nearer choosing a project host. You often have to have already chosen a license when you choose a host, so putting them together makes sense. Mention Pyflakes and Pychecker when you mention Pylint? Pylint is very powerful, but a real pain to configure. In testing resources you should link to the Python Testing Tools Taxonomy: http://pycheesecake.org/wiki/PythonTestingToolsTaxonomy Nothing more so far. :-) All the best, Michael > It's tentatively called the "Python Project Howto," and it's aimed at > people who, though not necessarily new to Python, may be new to > packaging and possibly open source. It tries to be succinct and > practical, demonstrating by example. It covers choosing project > hosting, setting up version control (Subversion basics), code quality > (Pylint) and style (PEP 8), documentation (reStructuredText, Sphinx), > unit testing (doctest and unittest), licensing, packaging (distutils), > and release (PyPI). > > One thing I don't want it to be is an exhaustive list of all the > possibilities for each of those areas. For instance, I cover > reStructuredText and Sphinx, but not epydoc; distutils but not > setuptools. I've tried to pick the simplest, most common among > several options, and sometimes provided a link to others (pip, nose). > I'm trying to Keep It Simple for people just dipping their toes into > the Python ecosystem. I'd really like to know what people think; it > would be great to get some feedback on it. Thanks! > > -John > _______________________________________________ > Doc-SIG maillist - Doc-SIG at python.org > http://mail.python.org/mailman/listinfo/doc-sig > -- http://www.ironpythoninaction.com/ From p.f.moore at gmail.com Wed Sep 30 17:42:18 2009 From: p.f.moore at gmail.com (Paul Moore) Date: Wed, 30 Sep 2009 16:42:18 +0100 Subject: [Doc-SIG] Request for Eyeballs: Python Project Howto In-Reply-To: <6496ee60909241615g7d94d1bar68a3be14ec4598b9@mail.gmail.com> References: <6496ee60909241615g7d94d1bar68a3be14ec4598b9@mail.gmail.com> Message-ID: <79990c6b0909300842l7465cb3bwfce06619078f2b56@mail.gmail.com> 2009/9/25 John Kleint : > I'm writing an introduction to releasing open-source Python projects. > Having recently gone through it for the first time myself, I was > amazed at how far and wide I had to range to pull together all the > information that goes into making a good Python package.? So I thought > I'd write it up and share: > > http://infinitemonkeycorps.net/docs/pph/ > > It's tentatively called the "Python Project Howto," and it's aimed at > people who, though not necessarily new to Python, may be new to > packaging and possibly open source. ?It tries to be succinct and > practical, demonstrating by example.? It covers choosing project > hosting, setting up version control (Subversion basics), code quality > (Pylint) and style (PEP 8), documentation (reStructuredText, Sphinx), > unit testing (doctest and unittest), licensing, packaging (distutils), > and release (PyPI). > > One thing I don't want it to be is an exhaustive list of all the > possibilities for each of those areas.? For instance, I cover > reStructuredText and Sphinx, but not epydoc; distutils but not > setuptools. ?I've tried to pick the simplest, most common among > several options, and sometimes provided a link to others (pip, nose). > I'm trying to Keep It Simple for people just dipping their toes into > the Python ecosystem.? I'd really like to know what people think; it > would be great to get some feedback on it. ?Thanks! Please, when describing how to build the uploadable packages, as well as setup.py sdist, add in a recommendation to build and upload setup.py bdist_wininst. Not all users (want to) use easy_install, and for those on Windows who don't, the provision of a Windows installer is a very useful convenience. It's not difficult, for pure Python packages (AFAIK, bdist_wininst is platform independent). If you're packaging up a C extension, you want to make sure it builds on Windows in any case, of course (:-)) so building an installer is no extra burden, and hugely helps your Windows users. I've fairly often not bothered trying out packages just because they don't provide a windows installer. Call me lazy, but even so... :-) Paul.