Report printing refactor

.gitignore

@@ -108,5 +108,6 @@ src/backend/InvenTree/web/static
 InvenTree/web/static
 
 # Generated docs files
+docs/schema.yml
 docs/docs/api/*.yml
 docs/docs/api/schema/*.yml

docs/docs/extend/plugins/action.md

@@ -15,4 +15,14 @@ POST {
 }
 ```
 
-For an example of a very simple action plugin, refer to `/src/backend/InvenTree/plugin/samples/integratoni/simpleactionplugin.py`
+### Sample Plugin
+
+A sample action plugin is provided in the `InvenTree` source code, which can be used as a template for creating custom action plugins:
+
+::: plugin.samples.integration.simpleactionplugin.SimpleActionPlugin
+    options:
+        show_bases: False
+        show_root_heading: False
+        show_root_toc_entry: False
+        show_source: True
+        members: []

docs/docs/extend/plugins/api.md

@@ -5,3 +5,15 @@ title: Schedule Mixin
 ## APICallMixin
 
 The APICallMixin class provides basic functionality for integration with an external API.
+
+### Sample Plugin
+
+The following example demonstrates how to use the `APICallMixin` class to make a simple API call:
+
+::: plugin.samples.integration.api_caller.SampleApiCallerPlugin
+    options:
+        show_bases: False
+        show_root_heading: False
+        show_root_toc_entry: False
+        show_source: True
+        members: []

docs/docs/extend/plugins/barcode.md

@@ -2,7 +2,7 @@
 title: Barcode Mixin
 ---
 
-### Barcode Plugins
+## Barcode Plugins
 
 InvenTree supports decoding of arbitrary barcode data via a **Barcode Plugin** interface. Barcode data POSTed to the `/api/barcode/` endpoint will be supplied to all loaded barcode plugins, and the first plugin to successfully interpret the barcode data will return a response to the client.
 
@@ -24,7 +24,21 @@ POST {
 }
 ```
 
-### Example
+### Builtin Plugin
+
+The InvenTree server includes a builtin barcode plugin which can decode QR codes generated by the server. This plugin is enabled by default.
+
+::: plugin.builtin.barcodes.inventree_barcode.InvenTreeInternalBarcodePlugin
+    options:
+        show_bases: False
+        show_root_heading: False
+        show_root_toc_entry: False
+        show_source: True
+        members: []
+
+
+### Example Plugin
+
 Please find below a very simple example that is executed each time a barcode is scanned.
 
 ```python

docs/docs/extend/plugins/currency.md

@@ -6,7 +6,24 @@ title: Currency Exchange Mixin
 
 The `CurrencyExchangeMixin` class enabled plugins to provide custom backends for updating currency exchange rate information.
 
-Any implementing classes must provide the `update_exchange_rates` method. A simple example is shown below (with fake data).
+Any implementing classes must provide the `update_exchange_rates` method.
+
+### Builtin Plugin
+
+The default builtin plugin for handling currency exchange rates is the `InvenTreeCurrencyExchangePlugin` class.
+
+::: plugin.builtin.integration.currency_exchange.InvenTreeCurrencyExchange
+    options:
+        show_bases: False
+        show_root_heading: False
+        show_root_toc_entry: False
+        show_source: True
+        members: []
+
+
+### Sample Plugin
+
+A simple example is shown below (with fake data).
 
 ```python
 

docs/docs/extend/plugins/event.md

@@ -15,56 +15,34 @@ When a certain (server-side) event occurs, the background worker passes the even
 {% include 'img.html' %}
 {% endwith %}
 
-### Example (all events)
+### Sample Plugin - All events
 
 Implementing classes must at least provide a `process_event` function:
 
-```python
-class EventPlugin(EventMixin, InvenTreePlugin):
-    """
-    A simple example plugin which responds to events on the InvenTree server.
+::: plugin.samples.event.event_sample.EventPluginSample
+    options:
+        show_bases: False
+        show_root_heading: False
+        show_root_toc_entry: False
+        show_source: True
+        members: []
 
-    This example simply prints out the event information.
-    A more complex plugin could respond to specific events however it wanted.
-    """
-
-    NAME = "EventPlugin"
-    SLUG = "event"
-    TITLE = "Triggered Events"
-
-    def process_event(self, event, *args, **kwargs):
-        print(f"Processing triggered event: '{event}'")
-```
-
-### Example (specific events)
+### Sample Plugin - Specific Events
 
 If you want to process just some specific events, you can also implement the `wants_process_event` function to decide if you want to process this event or not. This function will be executed synchronously, so be aware that it should contain simple logic.
 
 Overall this function can reduce the workload on the background workers significantly since less events are queued to be processed.
 
-```python
-class EventPlugin(EventMixin, InvenTreePlugin):
-    """
-    A simple example plugin which responds to 'salesordershipment.completed' event on the InvenTree server.
-
-    This example simply prints out the event information.
-    A more complex plugin can run enhanced logic on this event.
-    """
-
-    NAME = "EventPlugin"
-    SLUG = "event"
-    TITLE = "Triggered Events"
-
-    def wants_process_event(self, event):
-        """Here you can decide if this event should be send to `process_event` or not."""
-        return event == "salesordershipment.completed"
+::: plugin.samples.event.filtered_event_sample.FilteredEventPluginSample
+    options:
+        show_bases: False
+        show_root_heading: False
+        show_root_toc_entry: False
+        show_source: True
+        members: []
 
-    def process_event(self, event, *args, **kwargs):
-        """Here you can run you'r specific logic."""
-        print(f"Sales order was completely shipped: '{args}' '{kwargs}'")
-```
 
-### Events
+## Events
 
 Events are passed through using a string identifier, e.g. `build.completed`
 

docs/docs/extend/plugins/label.md

@@ -172,6 +172,14 @@ InvenTree supplies the `InvenTreeLabelPlugin` out of the box, which generates a
 
 The default plugin also features a *DEBUG* mode which generates a raw HTML output, rather than PDF. This can be handy for tracking down any template rendering errors in your labels.
 
+::: plugin.builtin.labels.inventree_label.InvenTreeLabelPlugin
+    options:
+        show_bases: False
+        show_root_heading: False
+        show_root_toc_entry: False
+        show_source: True
+        members: []
+
 ### Available Data
 
 The *label* data are supplied to the plugin in both `PDF` and `PNG` formats. This provides compatibility with a great range of label printers "out of the box". Conversion to other formats, if required, is left as an exercise for the plugin developer.

docs/docs/extend/plugins/locate.md

@@ -29,3 +29,15 @@ If a locate plugin is installed and activated, the [InvenTree mobile app](../../
 ### Implementation
 
 Refer to the [InvenTree source code](https://github.com/inventree/InvenTree/blob/master/src/backend/InvenTree/plugin/samples/locate/locate_sample.py) for a simple implementation example.
+
+### Sample Plugin
+
+A simple example is provided in the InvenTree code base:
+
+::: plugin.samples.locate.locate_sample.SampleLocatePlugin
+    options:
+        show_bases: False
+        show_root_heading: False
+        show_root_toc_entry: False
+        show_source: True
+        members: []

docs/docs/extend/plugins/panel.md

@@ -52,6 +52,18 @@ Or to add a template file that will be rendered as javascript code, from the plu
 
 Note : see convention for template directory above.
 
+## Sample Plugin
+
+A sample plugin is provided in the InvenTree code base:
+
+::: plugin.samples.integration.custom_panel_sample.CustomPanelSample
+    options:
+        show_bases: False
+        show_root_heading: False
+        show_root_toc_entry: False
+        show_source: True
+        members: []
+
 ## Example Implementations
 
 Refer to the `CustomPanelSample` example class in the `./plugin/samples/integration/` directory, for a fully worked example of how custom UI panels can be implemented.

docs/docs/extend/plugins/report.md

@@ -14,48 +14,14 @@ A plugin which implements the ReportMixin mixin can define the `add_report_conte
 
 Additionally the `add_label_context` method, allowing custom context data to be added to a label template at time of printing.
 
-### Example
+### Sample Plugin
 
-A sample plugin which provides additional context data to the report templates can be found [in the InvenTree source code](https://github.com/inventree/InvenTree/blob/master/src/backend/InvenTree/plugin/samples/integration/report_plugin_sample.py):
+A sample plugin which provides additional context data to the report templates is available:
 
-```python
-"""Sample plugin for extending reporting functionality"""
-
-import random
-
-from plugin import InvenTreePlugin
-from plugin.mixins import ReportMixin
-from report.models import PurchaseOrderReport
-
-
-class SampleReportPlugin(ReportMixin, InvenTreePlugin):
-    """Sample plugin which provides extra context data to a report"""
-
-    NAME = "Sample Report Plugin"
-    SLUG = "reportexample"
-    TITLE = "Sample Report Plugin"
-    DESCRIPTION = "A sample plugin which provides extra context data to a report"
-    VERSION = "1.0"
-
-    def some_custom_function(self):
-        """Some custom function which is not required for the plugin to function"""
-        return random.randint(0, 100)
-
-    def add_report_context(self, report_instance, model_instance, request, context):
-
-        """Add example content to the report instance"""
-
-        # We can add any extra context data we want to the report
-
-        # Generate a random string of data
-        context['random_text'] = ''.join(random.choices('abcdefghijklmnopqrstuvwxyz', k=20))
-
-        # Call a custom method
-        context['random_int'] = self.some_custom_function()
-
-        # We can also add extra data to the context which is specific to the report type
-        context['is_purchase_order'] = isinstance(report_instance, PurchaseOrderReport)
-
-        # We can also use the 'request' object to add extra context data
-        context['request_method'] = request.method
-```
+::: plugin.samples.integration.report_plugin_sample.SampleReportPlugin
+    options:
+        show_bases: False
+        show_root_heading: False
+        show_root_toc_entry: False
+        show_source: True
+        members: []

docs/docs/extend/plugins/schedule.md

@@ -18,45 +18,14 @@ The ScheduleMixin class provides a plugin with the ability to call functions at
 {% include 'img.html' %}
 {% endwith %}
 
-### Example
+### SamplePlugin
 
 An example of a plugin which supports scheduled tasks:
 
-```python
-class ScheduledTaskPlugin(ScheduleMixin, SettingsMixin, InvenTreePlugin):
-    """
-    Sample plugin which runs a scheduled task, and provides user configuration.
-    """
-
-    NAME = "Scheduled Tasks"
-    SLUG = 'schedule'
-
-    SCHEDULED_TASKS = {
-        'global': {
-            'func': 'some_module.function',
-            'schedule': 'H',  # Run every hour
-        },
-        'member': {
-            'func': 'foo',
-            'schedule': 'I',  # Minutes
-            'minutes': 15,
-        },
-    }
-
-    SETTINGS = {
-        'SECRET': {
-            'name': 'A secret',
-            'description': 'User configurable value',
-        },
-    }
-
-    def foo(self):
-        """
-        This function runs every 15 minutes
-        """
-        secret_value = self.get_setting('SECRET')
-        print(f"foo - SECRET = {secret_value})
-```
-
-!!! info "More Info"
-    For more information on any of the methods described below, refer to the InvenTree source code. [A working example is available as a starting point](https://github.com/inventree/InvenTree/blob/master/src/backend/InvenTree/plugin/samples/integration/scheduled_task.py).
+::: plugin.samples.integration.scheduled_task.ScheduledTaskPlugin
+    options:
+        show_bases: False
+        show_root_heading: False
+        show_root_toc_entry: False
+        show_source: True
+        members: []

docs/docs/extend/plugins/settings.md

@@ -15,7 +15,7 @@ The dict must be formatted similar to the following sample that shows how to use
 
 Take a look at the settings defined in `InvenTree.common.models.InvenTreeSetting` for all possible parameters.
 
-### Example
+### Example Plugin
 
 Below is a simple example of how a plugin can implement settings:
 

docs/docs/extend/plugins/validation.md

@@ -52,7 +52,7 @@ To indicate a *field* validation error (i.e. the validation error applies only t
 
 Note that an error can be which corresponds to multiple model instance fields.
 
-### Example
+### Example Plugin
 
 Presented below is a simple working example for a plugin which implements the `validate_model_instance` method:
 
@@ -182,3 +182,15 @@ def increment_serial_number(self, serial: str):
 
     return val
 ```
+
+## Sample Plugin
+
+A sample plugin which implements custom validation routines is provided in the InvenTree source code:
+
+::: plugin.samples.integration.validation_sample.SampleValidatorPlugin
+    options:
+        show_bases: False
+        show_root_heading: False
+        show_root_toc_entry: False
+        show_source: True
+        members: []

docs/docs/extend/themes.md

@@ -14,7 +14,7 @@ Navigate to the "Settings" page and click on the "Display" tab, you should see t
 {% include 'img.html' %}
 {% endwith %}
 
-The drop-down list let's you select any other color theme found in your static folder (see next section to find out how to [add color themes](#add-color-themes)). Once selected, click on the "Apply Theme" button for the new color theme to be activated.
+The drop-down list let's you select any other color theme found in your static folder (see next section to find out how to [add color themes](#add-color-theme)). Once selected, click on the "Apply Theme" button for the new color theme to be activated.
 
 !!! info "Per-user Setting"
 	Color themes are "user specific" which means that changing the color theme in your own settings won't affect other users.

docs/docs/order/return_order.md

@@ -98,7 +98,7 @@ While [line items](#line-items) must reference a particular stock item, extra li
 
 ## Return Order Reports
 
-Custom [reports](../report/return_order.md) can be generated against each Return Order.
+Custom [reports](../report/templates.md) can be generated against each Return Order.
 
 ### Calendar view
 

docs/docs/releases/0.1.6.md

@@ -24,7 +24,7 @@ Refer to the [report documentation](../report/report.md) for further information
 !!! warning "LaTeX Support"
     LaTeX report templates are no longer supported for a number of technical and ideological reasons
 
-[#1292](https://github.com/inventree/InvenTree/pull/1292) adds support for build order / work order reports. Refer to the [build report documentation](../report/build.md) for further information.
+[#1292](https://github.com/inventree/InvenTree/pull/1292) adds support for build order / work order reports. Refer to the [report documentation](../report/templates.md) for further information.
 
 ### Inherited BOM Items