diff --git a/docs/architecture.rst b/docs/architecture.rst new file mode 100644 index 000000000..7be5ac78d --- /dev/null +++ b/docs/architecture.rst @@ -0,0 +1,84 @@ +Architecture +============ + +The Django Debug Toolbar is designed to be flexible and extensible for +developers and third-party panel creators. + +Core Components +--------------- + +While there are several components, the majority of logic and complexity +lives within the following: + +- ``debug_toolbar.middleware.DebugToolbarMiddleware`` +- ``debug_toolbar.toolbar.DebugToolbar`` +- ``debug_toolbar.panels`` + +^^^^^^^^^^^^^^^^^^^^^^ +DebugToolbarMiddleware +^^^^^^^^^^^^^^^^^^^^^^ + +The middleware is how the toolbar integrates with Django projects. +It determines if the toolbar should instrument the request, which +panels to use, facilitates the processing of the request and augmenting +the response with the toolbar. Most logic for how the toolbar interacts +with the user's Django project belongs here. + +^^^^^^^^^^^^ +DebugToolbar +^^^^^^^^^^^^ + +The ``DebugToolbar`` class orchestrates the processing of a request +for each of the panels. It contains the logic that needs to be aware +of all the panels, but doesn't need to interact with the user's Django +project. + +^^^^^^ +Panels +^^^^^^ + +The majority of the complex logic lives within the panels themselves. This +is because the panels are responsible for collecting the various metrics. +Some of the metrics are collected via +`monkey-patching `_, such as +``TemplatesPanel``. Others, such as ``SettingsPanel`` don't need to collect +anything and include the data directly in the response. + +Some panels such as ``SQLPanel`` have additional functionality. This tends +to involve a user clicking on something, and the toolbar presenting a new +page with additional data. That additional data is handled in views defined +in the panels package (for example, ``debug_toolbar.panels.sql.views``). + +Logic Flow +---------- + +When a request comes in, the toolbar first interacts with it in the +middleware. If the middleware determines the request should be instrumented, +it will instantiate the toolbar and pass the request for processing. The +toolbar will use the enabled panels to collect information on the request +and/or response. When the toolbar has completed collecting its metrics on +both the request and response, the middleware will collect the results +from the toolbar. It will inject the HTML and JavaScript to render the +toolbar as well as any headers into the response. + +After the browser renders the panel and the user interacts with it, the +toolbar's JavaScript will send requests to the server. If the view handling +the request needs to fetch data from the toolbar, the request must supply +the store ID. This is so that the toolbar can load the collected metrics +for that particular request. + +The history panel allows a user to view the metrics for any request since +the application was started. The toolbar maintains its state entirely in +memory for the process running ``runserver``. If the application is +restarted the toolbar will lose its state. + +Problematic Parts +----------------- + +- ``debug.panels.templates.panel``: This monkey-patches template rendering + when the panel module is loaded +- ``debug.panels.sql``: This package is particularly complex, but provides + the main benefit of the toolbar +- Support for async and multi-threading: This is currently unsupported, but + is being implemented as per the + `Async compatible toolbar project `_. diff --git a/docs/changes.rst b/docs/changes.rst index 7e166d3b2..fd79230af 100644 --- a/docs/changes.rst +++ b/docs/changes.rst @@ -11,6 +11,8 @@ Pending return invalid json. * Render forms with ``as_div`` to silence Django 5.0 deprecation warnings. * Stayed on top of pre-commit hook updates. +* Added :doc:`architecture documentation ` to help + on-board new contributors. 4.3.0 (2024-02-01) ------------------ diff --git a/docs/contributing.rst b/docs/contributing.rst index 5e11ee603..55d9a5ca7 100644 --- a/docs/contributing.rst +++ b/docs/contributing.rst @@ -48,6 +48,12 @@ For convenience, there's an alias for the second command:: Look at ``example/settings.py`` for running the example with another database than SQLite. +Architecture +------------ + +There is high-level information on how the Django Debug Toolbar is structured +in the :doc:`architecture documentation `. + Tests ----- diff --git a/docs/index.rst b/docs/index.rst index e53703d4f..e72037045 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -12,3 +12,4 @@ Django Debug Toolbar commands changes contributing + architecture