[Checkins] SVN: z3c.autoinclude/trunk/ update README

Ethan Jucovy ejucovy at openplans.org
Fri Feb 13 17:54:37 EST 2009


Log message for revision 96510:
  update README

Changed:
  U   z3c.autoinclude/trunk/README.txt
  U   z3c.autoinclude/trunk/setup.py

-=-
Modified: z3c.autoinclude/trunk/README.txt
===================================================================
--- z3c.autoinclude/trunk/README.txt	2009-02-13 22:47:39 UTC (rev 96509)
+++ z3c.autoinclude/trunk/README.txt	2009-02-13 22:54:37 UTC (rev 96510)
@@ -1,32 +1,37 @@
-This package adds two new ZCML directives: "includeDependencies"
-and "includePlugins".
+This package adds two new ZCML directives to automatically detect 
+ZCML files to include: "includeDependencies" and "includePlugins".
 
+When you want to include a Zope-based package in your application, you
+have to repeat yourself in two places: you have to add the package
+itself (in a setup.py, buildout, etc) and you also have to include its
+ZCML with an <include> directive or a package-includes slug. Because
+you have to repeat yourself, you can easily make an error where you
+add a new package but forget to include its ZCML.
+
+z3c.autoinclude lets you circumvent this error-prone process with
+automatic detection and inclusion of ZCML files.
+
+== includeDependencies ==
+
 The "includeDependencies" directive searches through the dependencies
-in your setup.py file (install_requires), and includes the meta.zcml
-and configure.zcml files in those packages that it finds. Inclusion
-order matches the order in the setup.py file. You can pass a path for
-the package you want to include dependencies for, but typically you
-pass in the current package, as follows::
+in your setup.py file (install_requires), and includes the ZCML files
+in those packages that it finds. Inclusion order matches the order in
+the setup.py file. You can pass a path for the package you want to
+include dependencies for, but typically you pass in the current
+package, as follows::
 
   <includeDependencies package="." />
 
-The motivation behind this is to prevent having to repeat yourself in
-two places when you want to depend on a Zope 3 or Grok-based
-dependency: in the ``setup.py`` (in ``install_requires``) to make the
-dependency known, and again in ``configure.zcml`` with an ``include``
-statement to make sure the dependency's ZCML file are
-included. Because you have to repeat yourself, you can easily make an
-error where you add a new dependency in ``setup.py``, but forget to
-include the ZCML as well. If your package uses the ``autoinclude``
-directive, adding the includes for the ZCML configuration of
-individual dependencies is no longer necessary.
+With this directive, you no longer have to add an explicit ``<include
+package=new.dependency>`` for every new dependency of your project.
 
-The next versions of Grok_ and grokproject_ will use this functionality
-out of the box. The grokproject command will automatically add the
-``includeDependencies`` directive in the ZCML of the project it generates.
-You can then stop worrying about manual ZCML inclusion in the vast
-majority of cases.
+Grok_ and grokproject_ use this functionality out of the box. The
+grokproject command will automatically add the ``includeDependencies``
+directive in the ZCML of the project it generates.  You can then stop
+worrying about manual ZCML inclusion in the vast majority of cases.
 
+== includePlugins ==
+
 The "includePlugins" directive uses entry points to find installed
 packages that broadcast themselves as plugins to a particular base
 package. You can pass a path for the package you want to include
@@ -43,13 +48,10 @@
   target = my_base
   """
 
-The z3c.autoinclude directives automatically include
-``configure.zcml`` and ``meta.zcml`` files that live in the main
-package directories. In some cases, a package may use unusual names or
-locations for its ZCML files. In that case you will need to modify
-your package's ``configure.zcml`` and ``meta.zcml`` yourself to
-include the ZCML using the manual ``include`` directive.
+== The Details ==
 
+=== Setup === 
+
 To make the z3c.autoinclude directives available for use in your
 application or framework, you need to include it (in your
 ``meta.zcml`` for instance), like this::
@@ -58,6 +60,39 @@
 
 Grok already does this for you automatically.
 
+=== Disabling z3c.autoinclude ===
+
+It is often useful to disable z3c.autoinclude's functionality for
+debugging purposes or test runs.  To disable autoinclusion, set
+the environment variables "Z3C_AUTOINCLUDE_DEPENDENCIES_DISABLED" and
+"Z3C_AUTOINCLUDE_PLUGINS_DISABLED".
+
+When autoinclusion is disabled, the autoinclusion directives will
+issue a warning to the log and do nothing.
+
+=== ZCML Filenames ===
+
+The includeDependencies directive automatically includes
+``configure.zcml`` and ``meta.zcml`` files that live in the main
+package directories. For automatic inclusion of dependencies'
+overrides, there is an <includeDependenciesOverrides> directive.
+
+In some cases, a package may use unusual names or
+locations for its ZCML files. In that case you will need to modify
+your package's ``configure.zcml`` and ``meta.zcml`` yourself to
+include the ZCML using the manual ``include`` directive.
+
+The includePlugins directive automatically includes ``configure.zcml``
+and ``meta.zcml`` files by default, and the includePluginsOverrides
+directive automatically includes ``overrides.zcml`` files by default.
+But, like "<include>", these directives also have an optional "file"
+parameter, so you can automatically include all ``foo.zcml`` files in
+your package's plugins like this::
+
+  <includePlugins package="." file="foo.zcml" />
+
+The includeDependencies directives will soon offer this option as well.
+
 .. _Grok: http://grok.zope.org
 
 .. _grokproject: http://pypi.python.org/pypi/grokproject

Modified: z3c.autoinclude/trunk/setup.py
===================================================================
--- z3c.autoinclude/trunk/setup.py	2009-02-13 22:47:39 UTC (rev 96509)
+++ z3c.autoinclude/trunk/setup.py	2009-02-13 22:54:37 UTC (rev 96510)
@@ -6,7 +6,7 @@
 
 setup(name='z3c.autoinclude',
       version='0.3dev',
-      description="Automatically include ZCML for dependencies.",
+      description="Automatically include ZCML",
       long_description=long_description,
       # Get more strings from http://www.python.org/pypi?%3Aaction=list_classifiers
       classifiers=[



More information about the Checkins mailing list