Fleshed out Sphinx documentation skelington.

git-svn-id: svn+ssh://svn.repoze.org/svn/compoze/trunk@8601 8f1d8bf8-68d2-4fbe-a113-2afb08c80ed9

CHANGES.txt

@@ -4,6 +4,8 @@ compoze Changelog
 After compoze 0.2
 -----------------
 
+- Added Sphinx documentation.
+
 - Switched to using ``pkginfo`` to parse package information.
 
 - Added ``pool`` command which moves all archives in the current directory

README.txt

@@ -1,62 +1,12 @@
 compoze README
+==============
 
-  Overview
+This package provides a script for creating ``setuptools``-compatible
+package indexes using packages downloaded from other indexes.
 
-    This package provides a script for creating setuptools-compatible
-    package indexes using packages downloaded from other indexes.
+Please see ``docs/index.rst`` for the documentation, which can also be
+read online at:
 
-  Installation
-
-    Installing 'compoze' via 'easy_install' (it doesn't
-    depend on any other 'repoze' packages), creates a script,
-    'compoze', in the scripts directory of your Python::
-
-      $ bin/easy_install -i http://dist.repoze.org/simple compoze
-
-  Fetching Distributions
-
-    The 'compoze fetch' command is useful for retrieving distutils
-    distributions matching a set requirment specifications, e.g::
-
-      $ bin/compoze fetch --path=/tmp/index \
-                    --index-url=http://dist.repoze.org/simple \
-                    repoze.grok "repoze.project>=2.1"
-
-    If you do not supply an index URL, 'compoze' uses the Python
-    Package Index (the "cheeseshop") by default::
-
-      $ bin/compoze fetch --path=/tmp/index someproject
-
-    You can supply more than one "source" index::
-
-      $ bin/compoze fetch --path=/tmp/index \
-                    --index-url=http://example.com/index \
-                    --index-url=http://another.example.com/index \
-                    someproject another_project
-
-    If you do not supply a path, 'compoze fetch' uses the current
-    directory.
-
-  Example: Recreating the Package Set Already Installed
-
-    You can also ask to have 'compoze' fetch distributions for the eggs
-    already installed in site-packges::
-
-      $ bin/compoze fetch --path=/tmp/plone --fetch-site-packages
-
-  Building a Package Index
-
-    'compoze index' will make a PyPI-like package index in the
-    target directory::
-
-      $ bin/compoze index --path=/tmp/downloads
-
-  Example:  Creating a Package Index for the Versions Already Installed
-
-    One common use case is to capture the "known good set" represented
-    by a given Python environment.  In this case, you want both to download
-    the distributions corresponding to the projects installed in site-packages,
-    and also make a package index from them::
-
-      $ bin/compoze fetch --fetch-site-packages --path kgs \
-                    index --path kgs
+ http://docs.repoze.org/compoze
+
+ http://packages.python.org/compoze

compoze/compozer.py

@@ -1,5 +1,7 @@
-""" compoze -- command driver
+""" Generic command line driver.
 
+Register sub-commands by querying :mod:`setuptools` entry points for the
+group ``compoze_commands``.
 """
 import optparse
 import pkg_resources
@@ -27,15 +29,20 @@ def get_description(command):
 
 
 class Compozer:
-
+    """ Driver for the :command:`compoze` command-line script. 
+    """
     def __init__(self, argv=None, logger=None):
-
-        mine = []
-        queue = [(None, mine)]
         self.commands = []
         if logger is None:
             logger = self._print
         self.logger = logger
+        self.parse_arguments(argv)
+
+    def parse_arguments(self, argv=None):
+        """ Parse subcommands and their options from an argv list.
+        """
+        mine = []
+        queue = [(None, mine)]
 
         def _recordCommand(arg):
             current, current_args = queue[-1]
@@ -106,7 +113,8 @@ def _recordCommand(arg):
             raise ValueError('No commands specified')
 
     def __call__(self):
-
+        """ Invoke sub-commands parsed by :meth:`parse_arguments`.
+        """
         for command in self.commands:
             command()
 

compoze/fetcher.py

@@ -10,7 +10,7 @@
 
 
 class Fetcher:
-    """Download distributions for given requirements
+    """ Download distributions for a set of :mod:`setuptools` requirements.
     """
     index_factory = CompozePackageIndex # allow shimming for testing
 
@@ -109,10 +109,12 @@ def blather(self, text):
             self._logger(text)
 
     def download_distributions(self):
+        """ Collect best sdist candidate for each requirement into a tempdir.
 
-        # First, collect best sdist candidate for the requirement
-        # from each index into a self.tmpdir
+        Search each index and find-links URL provided in command options.
 
+        Report results using the logger.
+        """
         # XXX ignore same-name problem for now
 
         self.blather('=' * 50)
@@ -182,7 +184,8 @@ def download_distributions(self):
             self.blather('  ' + str(x))
 
     def __call__(self): #pragma NO COVERAGE
-
+        """ Call :meth:`download_distributions` and clean up.
+        """
         self.tmpdir = tempfile.mkdtemp(dir='.')
         try:
             self.download_distributions()

compoze/index.py

@@ -2,7 +2,10 @@
 
 
 class CompozePackageIndex(PackageIndex):
+    """ Override logging of :class:`setuptools.package_index.PackageIndex`.
 
+    Collect logged messages, rather than spewing to :data:`sys.stdout`.
+    """
     def __init__(self, *args, **kwargs):
         PackageIndex.__init__(self, *args, **kwargs)
         self.debug_msgs = []

compoze/indexer.py

@@ -1,6 +1,3 @@
-""" compoze index -- build a Python package index in a directory
-
-"""
 import optparse
 import os
 import pkginfo
@@ -140,7 +137,10 @@ def blather(self, text):
             self._logger(text)
 
     def make_index(self, path=None):
+        """ Build an index from a directory full of source distributions.
 
+        `path`, if passed, overrides the value set from the command line.
+        """
         if path is None:
             path = self.path
 
@@ -205,7 +205,8 @@ def make_index(self, path=None):
         top.close()
 
     def __call__(self): #pragma NO COVERAGE
-
+        """ Call :meth:`make_index` and clean up.
+        """
         self.tmpdir = tempfile.mkdtemp(dir='.')
         try:
             self.make_index()

compoze/informer.py

@@ -1,6 +1,3 @@
-""" compoze show -- show info about distributions for specified requirements
-
-"""
 import optparse
 import pkg_resources
 import sys
@@ -87,7 +84,8 @@ def blather(self, text):
             self._logger(text)
 
     def show_distributions(self):
-
+        """ Show available distributions for each index.
+        """
         for index_url in self.options.index_urls:
             self.blather('=' * 50)
             self.blather('Package index: %s' % index_url)
@@ -104,7 +102,8 @@ def show_distributions(self):
         self.blather('=' * 50)
 
     def __call__(self): #pragma NO COVERAGE
-
+        """ Delegate to :meth:`show_distributions`.
+        """
         self.show_distributions()
 
     def _expandRequirements(self, args):

compoze/pooler.py

@@ -74,7 +74,11 @@ def listArchives(self):
                 all.append(filename)
         return all, pending
 
-    def moveToPool(self):
+    def move_to_pool(self):
+        """ Move archives the pool directory and create symlinks.
+
+        Ignore any archives which are already symlinks.
+        """
         all, pending = self.listArchives()
         if len(all) == 0:
             raise ValueError('No non-link archives in release dir: %s'
@@ -101,8 +105,10 @@ def moveToPool(self):
         return all, pending
 
     def __call__(self): #pragma NO COVERAGE
+        """ Delegate to :meth:`move_to_pool` and report results.
+        """
         try:
-            all, pending = self.moveToPool()
+            all, pending = self.move_to_pool()
             self.blather(
                 "Updated %i out of %i archives" % (len(pending), len(all)))
         except ValueError, e:

compoze/tests/test_pooler.py

@@ -129,26 +129,26 @@ def test_listArchves_already_in_pool(self):
         self.assertEqual(fetcher.listArchives(),
                         (['foo.tar.gz'], []))
 
-    def test_moveToPool_no_archives_in_release_dir_raises(self):
+    def test_move_to_pool_no_archives_in_release_dir_raises(self):
         release_dir = self._makeTempDir()
         pool_dir = self._makeTempDir()
         fetcher = self._makeOne('--quiet',
                                 '--path=%s' % release_dir,
                                 pool_dir,
                                )
-        self.assertRaises(ValueError, fetcher.moveToPool)
+        self.assertRaises(ValueError, fetcher.move_to_pool)
 
-    def test_moveToPool_invalid_pool_dir_raises(self):
+    def test_move_to_pool_invalid_pool_dir_raises(self):
         release_dir = self._makeTempDir()
         self._makeFile(release_dir, 'foo.tar.gz')
         pool_dir = self._makeTempDir()
         fetcher = self._makeOne('--quiet',
                                 '--path=%s' % release_dir,
                                 self._makeFile(pool_dir, 'foolish'),
                                )
-        self.assertRaises(ValueError, fetcher.moveToPool)
+        self.assertRaises(ValueError, fetcher.move_to_pool)
 
-    def test_moveToPool_creates_pool_dir(self):
+    def test_move_to_pool_creates_pool_dir(self):
         import os
         release_dir = self._makeTempDir()
         source = self._makeFile(release_dir, 'foo.tar.gz')
@@ -158,13 +158,13 @@ def test_moveToPool_creates_pool_dir(self):
                                 '--path=%s' % release_dir,
                                 newdir,
                                )
-        fetcher.moveToPool()
+        fetcher.move_to_pool()
 
         self.failUnless(os.path.isdir(newdir))
         self.failUnless(os.path.isfile(os.path.join(newdir, 'foo.tar.gz')))
         self.failUnless(os.path.islink(source))
 
-    def test_moveToPool_existing_in_pool_dir(self):
+    def test_move_to_pool_existing_in_pool_dir(self):
         import os
         release_dir = self._makeTempDir()
         source = self._makeFile(release_dir, 'foo.tar.gz', 'SOURCE')
@@ -174,7 +174,7 @@ def test_moveToPool_existing_in_pool_dir(self):
                                 '--path=%s' % release_dir,
                                 pool_dir,
                                )
-        fetcher.moveToPool()
+        fetcher.move_to_pool()
 
         self.failUnless(os.path.isfile(target))
         self.assertEqual(open(target).read(), 'TARGET') # not replaced