[Zope-dev] reusability markers in our documentation

[Martijn Faassen]

Hi there,

In the "ZTK futures" thread Chris McDonough pointed out that right now 
we don't signal which packages are easily reusable outside of the Zope 
Toolkit and which packages aren't, and need a great knowledge of the way 
the Zope Toolkit works and a large amount of installed packages.

In order to increase our focus on reusable packages that stand on their 
own, and to reduce confusion by the outside world, we should signal 
clearly which packages should be considered by the broader community, 
and more importantly, which packages they can safely ignore.

I've therefore created the following guideline in the Zope Toolkit 
decisions document:

   Some Zope Toolkit packages are quite reusable without having to buy
   into the rest of the Zope Toolkit. Others aren't reusable at all
   without pulling in a huge chunk of the Zope Toolkit; they depend on
   many assumptions.

   We should communicate this clearly to potential users. As a first
   step, we will make sure these notifications are available on the
   PyPI pages. We will do this by adding a message about reusability to
   the long_description (which gets displayed on PyPI). Typically this
   is done by modifying the package's README.txt or
   ``src/zope/../README.txt`` doctest.

   The following text should be used for reusable packages::

     *This package is intended to be independently reusable in any Python
     project. It is maintained by the* `Zope Toolkit project
     <http://docs.zope.org/zopetoolkit/>`_.

   The following text should be used for packages that are *not*
   easily reusable::

     *This package is at present not reusable without depending on a
     large chunk of the Zope Toolkit and its assumptions. It is
     maintained by the* `Zope Toolkit project
     <http://docs.zope.org/zopetoolkit/>`_.

   At the time of writing, most of our packages will be marked as *not*
   reusable. Only packages at the roots of our dependency tree that
   have a clear purpose and some documentation (such as
   ``zope.interface`` and ``zope.component``) should be marked as
   reusable. We will slowly start to build up from there.

Help is needed to mark these packages. As a safe assumption, all 
zope.app.* packages should be marked as not reusable. It's a simple 
matter of going to the setup.py, seeing what file ends up being the 
start of long_description (typically README.txt or something like that) 
and modifying it with the marker text.

I've marked zope.component, zope.interface and zope.schema as 
"reusable". That doesn't mean their documentation shouldn't be improved 
to support this; it should. But nevertheless it's pretty doable to reuse 
them today. We have more such packages; in case of any doubt about the 
status, please bring it up in discussions here.

I've marked zope.app.publication as not reusable already.

Volunteers to help mark the other packages?

Regards,

Martijn