[Distutils] How to separate dependencies for using my package vs developing my package?

[Kevin Teague]

With pip or easy_install, there isn't a formal way to describe a
different working set from the main application. However, you can use
a note in an INSTALL.txt and optionally a pip requirements file
specifying specific versions. If there are package conflicts between
the main application dependencies in the support tools though, the
installs need to be in different locations.

With buildout, this use case can be formally described, and the
dependencies between the main application and the support tools are
kept distinct. Typically this might looks something like:

    [buildout]
    develop = .
    parts = myapp i18ndude releaser

    [myapp]
    recipe = zc.recipe.egg
    egg = myapp

    [i18ndude]
    recipe = zc.recipe.egg
    egg = i18ndude

    [releaser]
    recipe = zc.recipe.egg
    eggs = zest.releaser

Where the 'myapp' part would read the ./setup.py file for it's
dependencies, and the 'i18ndude' and 'zest.releaser' parts would read
the dependencies from the respective egg's install_requires fields.
Usually only tools which are specifically part of the workflow will
get put into a buildout.cfg inside the packages source tree. Then I'll
maintain a seperate buildout.cfg in my ~/bin/ directory for tools
which I use for developing, but don't want to enforce others to
install (generally these are tools such as boilerplate generation,
e.g. ZopeSkel):

    [buildout]
    parts = eggs
    bin-directory = .

    [eggs]
    recipe = zc.recipe.egg:scripts
    eggs = ZopeSkel
           PasteScript
           grokproject

If you have additional Python code which you want to specifically
support generating documentation for the project, you can do what Grok
does for managing it's documentation generation. Have a buildout.cfg
which specify's a documentation part (http://svn.zope.org/grok/trunk/
buildout.cfg?rev=109433&view=markup), but also specify that package
should be installed from a development version. Then embed the
development version of that package within the source tree of the main
package (in this case, there is a sub-directory named 'grokdocs'):

[buildout]
develop =
  .
  grokdocs

[docs]
recipe = zc.recipe.egg
eggs = grokdocs

Then in the 'grokdocs' subdirectory, the setup.py can be as
descriptive as it needs to be to set-up a specific documentation
publishing infrastructure.

In the Grok example, the 'grokdocs' package isn't published to PyPI,
so you can only generate the docs from an SVN checkout. If you want to
be able to generate docs from released versions only, then you need to
publish the package - although typically if you have a documentation
publishing process as part of your release process, then usually the
users can easily access docs that match a specific release and there
isn't any need to generate these yourself ...