Best practices for creating eggs?
Has anyone written up any best practices for creating eggs? How do people handle documentation? Our packages tend to have documentation files included as doctests, but It's not clear how folks are expected to get to them, especially if the eggs are zip files. -- Jim Fulton mailto:jim@zope.com Python Powered! CTO (540) 361-1714 http://www.python.org Zope Corporation http://www.zope.com http://www.zope.org
At 04:39 PM 6/28/2006 -0400, Jim Fulton wrote:
Has anyone written up any best practices for creating eggs?
How do people handle documentation?
I basically make web pages for them, or if it's small enough of a project, stick it in the long_description of setup() (usually by reading it from a README.txt file). Otherwise, I make the documentation home page be easily reachable via information in PyPI (e.g., make it the 'url' in 'setup()'). I assume that most people will read the docs on the web, and that if they want the documentation source, they will download the "sdist" distribution that I always upload alongside of the eggs.
Our packages tend to have documentation files included as doctests, but It's not clear how folks are expected to get to them, especially if the eggs are zip files.
I just post them to the web. In some cases, I have scripts that "svn up" and rebuild the docs nightly. For others with relatively short docs, I just upload them by hand. There's lots of opportunity to add more distutils or setuptools extensions for doc processing. I imagine that Zope projects will probably want to have some declarative or discoverable way to get docs built, so you can automate the process of updating browsable versions of the doc, or for that matter assist people in building their own docs from source. (By the way, "easy_install -eb somedir foo" will download and extract (or check out of Subversion) a copy of "foo" to "somedir/foo", so you are not limited to what is placed in an egg for execution/import purposes; I assume the typical user will read docs online, and thus most installations and downloads do not need to carry substantial documentation.)
On 6/28/06, Phillip J. Eby <pje@telecommunity.com> wrote:
I assume that most people will read the docs on the web, and that if they want the documentation source, they will download the "sdist" distribution that I always upload alongside of the eggs.
I work offline sufficiently often that not having local documentation is frustrating. There's no standard for local docs, which is a nuisance, and makes for an inconsistent story between different packages, but I'd be concerned if setuptools made it more difficult to bundle local docs. An example - cx_Oracle provides a full set of HTML documentation which the bdist_wininst installer drops in C:\Python24\cx_Oracle-doc. The one time I tried using easy_install to convert this to an egg, the documentation got missed out. I've never retried the experiment, however, so things could well have changed, as this was quite a while ago. And of course, eggs which get installed as zip files don't really offer anywhere to *put* documentation which is accessible (web browsers can't load HTML out of zip files, for example). Paul.
On Jun 29, 2006, at 5:37 AM, Paul Moore wrote:
On 6/28/06, Phillip J. Eby <pje@telecommunity.com> wrote:
I assume that most people will read the docs on the web, and that if they want the documentation source, they will download the "sdist" distribution that I always upload alongside of the eggs.
I work offline sufficiently often that not having local documentation is frustrating. There's no standard for local docs, which is a nuisance, and makes for an inconsistent story between different packages, but I'd be concerned if setuptools made it more difficult to bundle local docs.
I'll second this (or is it third, since Jim was asking something similar)? Being able to get at a package's documentation after it's installed would be nice. If you use docstrings, at least you can use help() and pydoc for apidocs. Kevin
On 6/29/06, Kevin Dangoor <dangoor@gmail.com> wrote:
If you use docstrings, at least you can use help() and pydoc for apidocs.
Agreed, but existing HTML (or HTML-help, or other format) documentation often covers more than docstrings alone do (tutorial stuff, user guides, etc). I'd rather not discourage this type of documentation either. Paul.
participants (4)
-
Jim Fulton -
Kevin Dangoor -
Paul Moore -
Phillip J. Eby