# HG changeset patch
# User Laurent Peuch <cortex@worlddomination.be>
# Date 1576643982 -3600
# Node ID 053329493511583c65824dca033f32402e1d79f1
# Parent  3954554f5b4868f3765fc6a4c75c0195e9bf1f96
[doc] document debug toolbar

diff -r 3954554f5b48 -r 053329493511 doc/book/pyramid/debug_toolbar.rst
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/book/pyramid/debug_toolbar.rst	Wed Dec 18 05:39:42 2019 +0100
@@ -0,0 +1,115 @@
+.. _debug-toolbar_pyramid:
+
+The pyramid debug toolbar
+=========================
+
+The pyramid webserver comes with an integrated `debug toolbar
+<https://docs.pylonsproject.org/projects/pyramid_debugtoolbar/>`_ that offers a
+lot of information to ease development. To ease the development process in
+CubicWeb a series of custom debug panels have been developped especially for
+that purpose.
+
+To use the pyramid debug toolbar in CubicWeb, you need to:
+
+* install it either by doing a `pip install pyramid_debugtoobar` or following
+  `the official installation instructions
+  <https://docs.pylonsproject.org/projects/pyramid_debugtoolbar/#installation>`_
+* launch the pyramid command adding the `-t/--toolbar` argument to enable it
+  like so: `cubicweb-ctl pyramid my_instance -t` (you probably want to add `-D`
+  to activate the debug mode during development)
+* navigate to the website and click on the icon on the right like on this screenshot:
+
+.. image:: ../../images/debug_toolbar_icon.png
+
+And you'll have access to the debug toolbar content for this page.
+
+Custom panels
+-------------
+
+A series of custom debug panels have been written to offer more useful debug
+information during development. Here is the list:
+
+General 'CubicWeb' Panel
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+Provides:
+
+* currently selected controller for this with and uri/requests information
+* current instance configuration, options that differs from default ones are in bold
+* a list of useful links like on the default CW home
+
+Screenshot:
+
+.. image:: ../../images/debugtoolbar_general_panel.png
+
+Registry Decisions Panel
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+Provides:
+
+* a list of all decisions taken in all registry during this page construction
+* the arguments given to take the decision
+* all the selection entities during decisions with their score
+* which one has won if any
+
+.. image:: ../../images/debugtoolbar_registry_decisions_panel.png
+
+Registry Store
+~~~~~~~~~~~~~~
+
+Provides:
+
+* a listing of all the content of the different registries
+* for each entity its detailed information
+
+.. image:: ../../images/debugtoolbar_registry_content_panel.png
+
+RQL
+~~~
+
+Provides:
+
+* a list of all executed RQL queries during this page creation
+* for each RQL query all the generated SQL queries
+* detail information like the result, the args and the description of each query
+* the call stack on each query to see where it has been called
+
+.. image:: ../../images/debugtoolbar_rql_panel.png
+
+.. image:: ../../images/debugtoolbar_rql_traceback_panel.png
+
+SQL
+~~~
+
+Provides:
+
+* a list of all executed SQL queries during this page creation
+* for each SQL query the RQL query that has generated it, if any (some aren't)
+* detail information like the result, the args and if the query has rollback
+* the call stack on each query to see where it has been called
+
+.. image:: ../../images/debugtoolbar_sql_panel.png
+
+Accessing the sources of the class/functions/method listing the debug panels
+----------------------------------------------------------------------------
+
+A traversal of all those custom panels is the see the source code of all
+listing class/functions/methods. You can access those by:
+
+* clicking on the `[source]` close to the target when available
+* clicking on the file path in the traceback stack
+
+.. image:: ../../images/debugtoolbar_show_source_link.png
+.. image:: ../../images/debugtoolbar_traceback_source_link.png
+
+You be sent to a page looking like this:
+
+.. image:: ../../images/debugtoolbar_show_source.png
+
+Contributing
+------------
+
+All source code for the custom panels is located `here
+<https://hg.logilab.org/master/cubicweb/file/tip/cubicweb/pyramid/debugtoolbar_panels.py>`_
+and the documentation of how to write `custom toolbar panels here
+<https://docs.pylonsproject.org/projects/pyramid_debugtoolbar/en/latest/#adding-custom-panels>`_.
diff -r 3954554f5b48 -r 053329493511 doc/book/pyramid/index.rst
--- a/doc/book/pyramid/index.rst	Tue Dec 10 23:50:24 2019 +0100
+++ b/doc/book/pyramid/index.rst	Wed Dec 18 05:39:42 2019 +0100
@@ -29,6 +29,7 @@
     settings
     auth
     profiling
+    debug_toolbar
 
 Api Documentation
 =================