document 'includeme'

Chris McDonough

2011-01-16 314283a5bec3159d5a0c7e4d7028a0feecd47fa0

document 'includeme'

 docs/narr/advconfig.rst

@@ -338,6 +338,23 @@
Using ``include`` rather than calling the function directly will allow
:ref:`automatic_conflict_resolution` to work.

:meth:`pyramid.config.Configuration.include` can also accept a :term:`module`
as an argument:

.. code-block:: python
   :linenos:

   import myapp

   config.include(myapp)

For this to work properly, the ``myapp`` module must contain a callable with
the special name ``includeme``, which should perform configuration (like the
``add_routes`` callable we showed above as an example).

:meth:`pyramid.config.Configuration.include` can also accept a :term:`dotted
Python name` to a function or a module.

.. note: See :ref:`the_include_tag` for a declarative alternative to
   :meth:`pyramid.config.Configurator.include`.