# HG changeset patch
# User Christophe de Vienne <christophe@unlish.com>
# Date 1436187066 -7200
# Node ID 18dd303225cd3b37ab4ee5a39353201a5113c444
# Parent  c7a25122af4dc6cb7160ff19d5b3d6760e0bee5f
[doc] Document embedding in a pyramid app

diff -r c7a25122af4d -r 18dd303225cd docs/narr/ctl.rst
--- a/docs/narr/ctl.rst	Mon Jul 06 14:16:55 2015 +0200
+++ b/docs/narr/ctl.rst	Mon Jul 06 14:51:06 2015 +0200
@@ -20,11 +20,19 @@
 
     Run the server in the foreground.
 
-
 .. option:: --debug-mode
 
     Activate the repository debug mode (logs in the console and the debug
-    toolbar). Implies :option:`--no-daemon`
+    toolbar). Implies :option:`--no-daemon`.
+
+    Also force the following pyramid options:
+
+    .. code-block:: ini
+    
+        pyramid.debug_authorization = yes
+        pyramid.debug_notfound = yes
+        pyramid.debug_routematch = yes
+        pyramid.reload_templates = yes
 
 .. option:: -D, --debug
 
diff -r c7a25122af4d -r 18dd303225cd docs/narr/quickstart.rst
--- a/docs/narr/quickstart.rst	Mon Jul 06 14:16:55 2015 +0200
+++ b/docs/narr/quickstart.rst	Mon Jul 06 14:51:06 2015 +0200
@@ -1,26 +1,34 @@
 Quick start
 ===========
 
-.. highlight:: console
+.. highlight:: bash
 
-From CubicWeb
--------------
+Prerequites
+-----------
 
 -   Install everything (here with pip, possibly in a virtualenv)::
 
         pip install pyramid-cubicweb cubicweb-pyramid pyramid_debugtoolbar
-        
--   Make sure CubicWeb is in user mode::
+
+-   Have a working Cubicweb instance, for example:
 
-        export CW_MODE=user
+
+    -   Make sure CubicWeb is in user mode::
 
--   Create a CubicWeb instance, and install the 'pyramid' cube on it (see
-    :ref:`configenv` for more details on this step)::
+            export CW_MODE=user
 
-        cubicweb-ctl create pyramid myinstance
+    -   Create a CubicWeb instance, and install the 'pyramid' cube on it (see
+        :ref:`configenv` for more details on this step)::
+
+            cubicweb-ctl create pyramid myinstance
 
 -   Edit your ``~/etc/cubicweb.d/myinstance/all-in-one.conf`` and set values for
     :confval:`pyramid-auth-secret` and :confval:`pyramid-session-secret`.
+    *required if pyramid_cubicweb.auth and pyramid_cubiweb.session get
+    included, which is the default*
+
+From CubicWeb
+-------------
 
 -   Start the instance with the :ref:`'pyramid' command <cubicweb-ctl_pyramid>`
     instead of 'start'::
@@ -30,4 +38,22 @@
 In a pyramid application
 ------------------------
 
-Coming soon.
+-   Create a pyramid application
+
+-   Include pyramid_cubicweb:
+
+    .. code-block:: python
+
+        def includeme(config):
+            # ...
+            config.include('pyramid_cubicweb')
+            # ...
+
+-   Configure the instance name (in the .ini file):
+
+    .. code-block:: ini
+
+        cubicweb.instance = myinstance
+
+-   Configure the base-url and https-url in all-in-one.conf to match the ones
+    of the pyramid configuration (this is a temporary limitation).
diff -r c7a25122af4d -r 18dd303225cd docs/narr/settings.rst
--- a/docs/narr/settings.rst	Mon Jul 06 14:16:55 2015 +0200
+++ b/docs/narr/settings.rst	Mon Jul 06 14:51:06 2015 +0200
@@ -68,6 +68,19 @@
 
 The Pyramid CubicWeb specific configuration entries are:
 
+.. confval:: cubicweb.instance (string)
+
+    A CubicWeb instance name. Useful when the application is not run by
+    :ref:`cubicweb-ctl_pyramid`.
+
+.. confval:: cubicweb.debug (bool)
+
+    Enables the cubicweb debugmode. Works only if the instance is setup by
+    :confval:`cubicweb.instance`.
+
+    Unlike when the debugmode is set by the :option:`cubicweb-ctl pyramid --debug-mode`
+    command, the pyramid debug options are untouched.
+
 .. confval:: cubicweb.includes (list)
 
     Same as ``pyramid.includes``, but the includes are done after the cubicweb