Documentation WIP

RamezIssac · Jul 3, 2023 · 45ec03e · 45ec03e
1 parent 682e54e
commit 45ec03e
Show file tree

Hide file tree

Showing 25 changed files with 511 additions and 169 deletions.
diff --git a/docs/source/charts.rst b/docs/source/charts.rst
@@ -1,5 +1,5 @@
-Charting
----------
+Charting and Front End Customization
+=====================================
 
 Charts Configuration
 ---------------------

diff --git a/docs/source/concept.rst b/docs/source/concept.rst
@@ -1,65 +1,53 @@
 .. _structure:
 
-Structure
-==========
+How the documentation is organized
+==================================
+
+:ref:`Tutorial <tutorial>`
+--------------------------
+
+If you are new to Django Slick Reporting, start here. It's a step-by-step guide to building a simple report(s).
 
-If you haven't yet, please check https://django-slick-reporting.com for a quick walk-though with live code examples..
 
-And now, Let's explore the main components of Django Slick Reporting and what setting you can set on project level.
+:ref:`How-to guides <how_to>`
+-----------------------------
 
-Components
-----------
-These are the main components of Django Slick Reporting
+Practical, hands-on guides that show you how to achieve a specific goal with Django Slick Reporting. Like customizing the form, creating a computation field, etc.
 
-#. :ref:`Report View <report_view>`: A ``FormView`` CBV subclass with reporting capabilities allowing you to create different types of reports in the view.
-   It provide a default :ref:`Filter Form <filter_form>` to filter the report on.
-   It mimics the Generator API interface, so knowing one is enough to work with the other.
 
-#. :ref:`Generator <report_generator>`: Responsible for generating report and orchestrating and calculating the computation fields values and mapping them to the results.
-   It has an intuitive API that allows you to define the report structure and the computation fields to be calculated.
+:ref:`Topic Guides <topics>`
+----------------------------
 
-#. :ref:`Computation Field <computation_field>`: a calculation unit,like a Sum or a Count of a certain field.
-   Computation field class set how the calculation should be done. ComputationFields can also depend on each other.
+Discuss each type of reports you can create with Django Slick Reporting and their options.
 
-#. Charting JS helpers: Highcharts and Charts js helpers libraries to plot the data generated. so you can create the chart in 1 line in the view
+    * :ref:`Grouped report <group_by_topic>`: Similar to what we'd do with a GROUP BY sql statement. We group by a field and do some kind of calculations over the grouped records.
+    * :ref:`time_series`: A step up from the grouped report, where the calculations are computed for each time period (day, week, month, etc).
+    * :ref:`crosstab_reports`: Where the results shows the relationship between two or more variables. Example: Rows are the clients, columns are the products, and the intersection values are the sum of sales for each client and product combination. This report can be created in time series as well. Example: Rows are the clients, columns are the products, and the intersection values are the sum of sales for each client and product combination, for each month.
+    * :ref:`list_reports`: Similar to a django changelist, it's a direct view of the report model records with some extra features like sorting, filtering, pagination, etc.
+    * And other topics like how to customize the form, and extend the exporting options.
 
 
-Types of reports
-----------------
-We can categorize the output of the reports in this package into 4 sections:
+:ref:`Reference <reference>`
+----------------------------
 
-#. Grouped report: similar to what we'd do with a GROUP BY sql statement. We group by a field and do some kind of calculations over the grouped records.
-#. Time series report: a step up from the grouped report, where the calculations are computed for each time period (day, week, month, etc).
-#. Crosstab report: a report where the results shows the relationship between two or more variables. Example: Rows are the clients, columns are the products, and the intersection values are the sum of sales for each client and product combination. This report can be created in time series as well. Example: Rows are the clients, columns are the products, and the intersection values are the sum of sales for each client and product combination, for each month.
-#. List report: Similar to a django changelist, it's a direct view of the report model records with some extra features like sorting, filtering, pagination, etc.
+Detailed information about main on Django Slick Reporting's main components, such as the :ref:`Report View <report_view_options>`, :ref:`Generator <report_generator>`, :ref:`Computation Field <computation_field>`, etc.
 
+    #. :ref:`Report View <report_view_options>`: A ``FormView`` CBV subclass with reporting capabilities allowing you to create different types of reports in the view.
+       It provide a default :ref:`Filter Form <filter_form>` to filter the report on.
+       It mimics the Generator API interface, so knowing one is enough to work with the other.
 
+    #. :ref:`Generator <report_generator>`: Responsible for generating report and orchestrating and calculating the computation fields values and mapping them to the results.
+       It has an intuitive API that allows you to define the report structure and the computation fields to be calculated.
 
+    #. :ref:`Computation Field <computation_field>`: a calculation unit,like a Sum or a Count of a certain field.
+       Computation field class set how the calculation should be done. ComputationFields can also depend on each other.
 
-Settings
---------
+    #. Charting JS helpers: Highcharts and Charts js helpers libraries to plot the data generated. so you can create the chart in 1 line in the view
 
-1. ``SLICK_REPORTING_DEFAULT_START_DATE``: Default: the beginning of the current year
-2. ``SLICK_REPORTING_DEFAULT_END_DATE``: Default: the end of the current  year.
-3. ``SLICK_REPORTING_FORM_MEDIA``: Controls the media files required by the search form.
-   Defaults is:
 
-.. code-block:: python
 
-    SLICK_REPORTING_FORM_MEDIA = {
-        "css": {
-            "all": (
-                "https://cdn.datatables.net/v/bs4/dt-1.10.20/datatables.min.css",
-                "https://cdnjs.cloudflare.com/ajax/libs/Chart.js/2.9.3/Chart.min.css",
-            )
-        },
-        "js": (
-            "https://code.jquery.com/jquery-3.3.1.slim.min.js",
-            "https://cdn.datatables.net/v/bs4/dt-1.10.20/datatables.min.js",
-            "https://cdnjs.cloudflare.com/ajax/libs/Chart.js/2.9.3/Chart.bundle.min.js",
-            "https://cdnjs.cloudflare.com/ajax/libs/Chart.js/2.9.3/Chart.min.js",
-            "https://code.highcharts.com/highcharts.js",
-        ),
-    }
 
-4. ``SLICK_REPORTING_DEFAULT_CHARTS_ENGINE``: Controls the default chart engine used.
+Demo site
+---------
+
+If you haven't yet, please check https://django-slick-reporting.com for a quick walk-though with live code examples..
diff --git a/docs/source/howto/customize_frontend.rst b/docs/source/howto/customize_frontend.rst
@@ -0,0 +1,114 @@
+Charting and Front End Customization
+=====================================
+
+Charts Configuration
+---------------------
+
+Charts settings is a list of objects which each object represent a chart configurations.
+
+* type: what kind of chart it is: Possible options are bar, pie, line and others subject of the underlying charting engine.
+  Hats off to : `Charts.js <https://www.chartjs.org/>`_.
+* engine_name: String, default to ``SLICK_REPORTING_DEFAULT_CHARTS_ENGINE``. Passed to front end in order to use the appropriate chart engine.
+  By default supports `highcharts` & `chartsjs`.
+* data_source: Field name containing the numbers we want to plot.
+* title_source: Field name containing labels of the data_source
+* title: the Chart title. Defaults to the `report_title`.
+* plot_total if True the chart will plot the total of the columns. Useful with time series and crosstab reports.
+
+On front end, for each chart needed we pass the whole response to the relevant chart helper function and it handles the rest.
+
+
+
+
+The ajax response structure
+---------------------------
+
+Understanding how the response is structured is imperative in order to customize how the report is displayed on the front end
+
+Let's have a look
+
+.. code-block:: python
+
+
+    # Ajax response or `report_results` template context variable.
+    response = {
+        # the report slug, defaults to the class name all lower
+        "report_slug": "",
+        # a list of objects representing the actual results of the report
+        "data": [
+            {
+                "name": "Product 1",
+                "quantity__sum": "1774",
+                "value__sum": "8758",
+                "field_x": "value_x",
+            },
+            {
+                "name": "Product 2",
+                "quantity__sum": "1878",
+                "value__sum": "3000",
+                "field_x": "value_x",
+            },
+            # etc .....
+        ],
+        # A list explaining the columns/keys in the data results.
+        # ie: len(response.columns) == len(response.data[i].keys())
+        # It contains needed information about verbose name , if summable and hints about the data type.
+        "columns": [
+            {
+                "name": "name",
+                "computation_field": "",
+                "verbose_name": "Name",
+                "visible": True,
+                "type": "CharField",
+                "is_summable": False,
+            },
+            {
+                "name": "quantity__sum",
+                "computation_field": "",
+                "verbose_name": "Quantities Sold",
+                "visible": True,
+                "type": "number",
+                "is_summable": True,
+            },
+            {
+                "name": "value__sum",
+                "computation_field": "",
+                "verbose_name": "Value $",
+                "visible": True,
+                "type": "number",
+                "is_summable": True,
+            },
+        ],
+        # Contains information about the report as whole if it's time series or a a crosstab
+        # And what's the actual and verbose names of the time series or crosstab specific columns.
+        "metadata": {
+            "time_series_pattern": "",
+            "time_series_column_names": [],
+            "time_series_column_verbose_names": [],
+            "crosstab_model": "",
+            "crosstab_column_names": [],
+            "crosstab_column_verbose_names": [],
+        },
+        # A mirror of the set charts_settings on the ReportView
+        # ``ReportView`` populates the id and the `engine_name' if not set
+        "chart_settings": [
+            {
+                "type": "pie",
+                "engine_name": "highcharts",
+                "data_source": ["quantity__sum"],
+                "title_source": ["name"],
+                "title": "Pie Chart (Quantities)",
+                "id": "pie-0",
+            },
+            {
+                "type": "bar",
+                "engine_name": "chartsjs",
+                "data_source": ["value__sum"],
+                "title_source": ["name"],
+                "title": "Column Chart (Values)",
+                "id": "bar-1",
+            },
+        ],
+    }
+
+
diff --git a/docs/source/howto.rst → docs/source/howto/index.rst b/docs/source/howto.rst → docs/source/howto/index.rst
@@ -1,9 +1,13 @@
+.. _how_to:
+
 =======
 How To
 =======
+In this section we will go over some of the frequent tasks you will need to do when using ReportView.
+
 
 Customize the form
-------------------
+==================
 
 The filter form is automatically generated for convenience
 but you can override it and add your own Form.
@@ -125,3 +129,42 @@ Create your own Chart Engine
 
 Create a Custom ComputationField and reuse it
 ---------------------------------------------
+
+
+
+Add a new chart engine
+----------------------
+
+
+Add an exporting option
+-----------------------
+
+
+
+Work with categorical data
+--------------------------
+
+How to create a custom ComputationField
+---------------------------------------
+
+
+create custom columns
+---------------------
+
+
+format numbers in the datatable
+
+
+custom group by
+custom time series periods
+custom crosstab reports
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Topics:
+   :titlesonly:
+
+
+   customize_frontend
+
+
diff --git a/docs/source/howto/override_filter_form.rst b/docs/source/howto/override_filter_form.rst
diff --git a/docs/source/index.rst b/docs/source/index.rst
@@ -35,7 +35,7 @@ You can start by using ``ReportView`` which is a subclass of ``django.views.gene
     from .models import MySalesItems
 
 
-    class MonthlyProductSales(ReportView):
+    class ProductSales(ReportView):
 
         report_model = MySalesItems
         date_field = "date_placed"
@@ -61,7 +61,11 @@ You can start by using ``ReportView`` which is a subclass of ``django.views.gene
 
     # in urls.py
     from django.urls import path
-    from .views import MonthlyProductSales
+    from .views import ProductSales
+
+    urlpatterns = [
+        path("product-sales/", ProductSales.as_view(), name="product-sales"),
+    ]
 
 Demo site
 ----------
@@ -70,19 +74,19 @@ https://django-slick-reporting.com is a quick walk-though with live code example
 
 
 
-Next step :ref:`structure`
+Next step :ref:`tutorial`
 
 .. toctree::
    :maxdepth: 2
    :caption: Contents:
 
-   tutorial
    concept
-   report_view/index
+   tutorial
+   howto/index
+   topics/index
    charts
-   exporting
-   report_generator
-   computation_field
+   ref/index
+
 
 
 Indices and tables

diff --git a/docs/source/recipes.rst b/docs/source/recipes.rst
diff --git a/docs/source/computation_field.rst → docs/source/ref/computation_field.rst b/docs/source/computation_field.rst → docs/source/ref/computation_field.rst
diff --git a/docs/source/ref/index.rst b/docs/source/ref/index.rst
@@ -0,0 +1,16 @@
+.. _reference:
+
+Reference
+===========
+
+Below are links to the reference documentation for the various components of the Django slick reporting .
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Components:
+
+   computation_field
+   report_generator
+   view_options
+
+
diff --git a/docs/source/report_generator.rst → docs/source/ref/report_generator.rst b/docs/source/report_generator.rst → docs/source/ref/report_generator.rst
diff --git a/docs/source/ref/settings.rst b/docs/source/ref/settings.rst
@@ -0,0 +1,29 @@
+
+Settings
+========
+
+
+1. ``SLICK_REPORTING_DEFAULT_START_DATE``: Default: the beginning of the current year
+2. ``SLICK_REPORTING_DEFAULT_END_DATE``: Default: the end of the current  year.
+3. ``SLICK_REPORTING_FORM_MEDIA``: Controls the media files required by the search form.
+   Defaults is:
+
+.. code-block:: python
+
+    SLICK_REPORTING_FORM_MEDIA = {
+        "css": {
+            "all": (
+                "https://cdn.datatables.net/v/bs4/dt-1.10.20/datatables.min.css",
+                "https://cdnjs.cloudflare.com/ajax/libs/Chart.js/2.9.3/Chart.min.css",
+            )
+        },
+        "js": (
+            "https://code.jquery.com/jquery-3.3.1.slim.min.js",
+            "https://cdn.datatables.net/v/bs4/dt-1.10.20/datatables.min.js",
+            "https://cdnjs.cloudflare.com/ajax/libs/Chart.js/2.9.3/Chart.bundle.min.js",
+            "https://cdnjs.cloudflare.com/ajax/libs/Chart.js/2.9.3/Chart.min.js",
+            "https://code.highcharts.com/highcharts.js",
+        ),
+    }
+
+4. ``SLICK_REPORTING_DEFAULT_CHARTS_ENGINE``: Controls the default chart engine used.