Extend report documentation (#318)

* Small updates for reporting docs

* Fix navbar

* Add "media" link in navbar

* Extend documentation for reporting features and tags

docs/report/media.md

@@ -2,9 +2,13 @@
 title: Using media files
 ---
 
-## Images
+## Media Files
 
-To load images into the reports/labels the report helper must be loaded in the template. 
+*Media files* are any files uploaded to the InvenTree server by the user. These are stored under the `/media/` directory and can be accessed for use in custom reports or labels.
+
+**Load Report Functions**
+
+To load images into the reports/labels the report helper functions must first be loaded in the template:
 
 ```html
 {% raw %}
@@ -13,9 +17,79 @@ To load images into the reports/labels the report helper must be loaded in the t
 {% endraw %}
 ```
 
-### Assets
+### Uploaded Images
 
-You can add images to the reports and labels by using the asset template tag:
+You can access an uploaded image file if you know the *path* of the image, relative to the top-level `/media/` directory. To load the image into a report, use the `{% raw %}{% uploaded_image ... %}{% endraw %}` tag:
+
+```html
+{% raw %}
+<!-- Load the report helper functions -->
+{% load report %}
+<img src='{% uploaded_image "subdir/my_image.png" %}'/>
+{% endraw %}
+```
+
+!!! info "Missing Image"
+    If the supplied image filename does not exist, it will be replaced with a placeholder image file
+
+!!! warning "Invalid Image"
+    If the supplied file is not a valid image, it will be replaced with a placeholder image file
+
+### Part images
+
+A shortcut function is provided for rendering an image associated with a Part instance. You can render the image of the part using the `{% raw %}{% part_image ... %}{% endraw %}` template tag:
+
+```html
+{% raw %}
+<!-- Load the report helper functions -->
+{% load report %}
+<img src='{% part_image part %}'/>
+{% endraw %}
+```
+
+### Company Images
+
+A shortcut function is provided for rendering an image associated with a Company instance. You can render the image of the company using the `{% raw %}{% company_image ... %}{% endraw %}` template tag:
+
+```html
+{% raw %}
+<!-- Load the report helper functions -->
+{% load report %}
+<img src='{% company_image company %}'/>
+{% endraw %}
+```
+
+## InvenTree Logo
+
+A template tag is provided to load the InvenTree logo image into a report. You can render the logo using the `{% raw %}{% logo_image %}{% endraw %}` tag:
+
+```html
+{% raw %}
+{% load report %}
+<img src='{% logo_image %}'/>
+{% endraw %}
+```
+
+### Custom Logo
+
+If the system administrator has enabled a [custom logo](../start/config.md#customisation-options), then this logo will be used instead of the base InvenTree logo.
+
+This is a useful way to get a custom company logo into your reports.
+
+If you have a custom logo, but explicitly wish to load the InvenTree logo itself, add `custom=False` to the tag:
+
+```html
+{% raw %}
+{% load report %}
+<img src='{% logo_image custom=False %}'/>
+{% endraw %}
+```
+
+## Report Assets
+
+[Report Assets](./report.md#report-assets) are files specifically uploaded by the user for inclusion in generated reports and labels.
+
+You can add asset images to the reports and labels by using the `{% raw %}{% asset ... %}{% endraw %}` template tag:
 
 ```html
 {% raw %}
@@ -25,17 +99,3 @@ You can add images to the reports and labels by using the asset template tag:
 {% endraw %}
 ```
 
-!!! info "Assets location"
-    You need to place your asset images to the report/assets directory in the [data directory](../start/docker_dev.md/#data-directory)
-
-### Part images
-
-You can render the images of the parts using the part_image template tag:
-
-```html
-{% raw %}
-<!-- Load the report helper functions -->
-{% load report %}
-<img src='{% part_image part %}'/>
-{% endraw %}
-```

docs/report/purchase_order.md

@@ -0,0 +1,8 @@
+---
+title: Purchase Order Report
+---
+
+## Purchase Order Reports
+
+!!! missing "TODO"
+	This section requires further work

docs/report/report.md

@@ -31,7 +31,7 @@ Uploaded report template files are passed through the [django template rendering
 
 Each report template is provided a set of *context variables* which can be used when rendering the template.
 
-For example, rendering the name of a part (which is available in the particular template context as *part*) is as follows:
+For example, rendering the name of a part (which is available in the particular template context as `part`) is as follows:
 
 ```html
 {% raw %}
@@ -45,19 +45,46 @@ For example, rendering the name of a part (which is available in the particular
 {% endraw %}
 ```
 
-!!! info "Variables"
+### Context Variables
-  	Templates will have different variables available to them depending on the report type. Read the detail information on each report type for further information.
 
-### Context Data
+!!! info "Context Variables"
+  	Templates will have different variables available to them depending on the report type. Read the detailed information on each available report type for further information.
 
 Please refer to the [Context variables](./context_variables.md) page.
 
 ### Conditional Rendering
 
-The django template system allows for conditional rendering, providing conditional flow statements such as `{% raw %}{% if <condition> %}{% endraw %}`, `{% raw %}{% for <item> in <list> %}{% endraw %}`, etc.
+The django template system allows for conditional rendering, providing conditional flow statements such as:
+
+```
+{% raw %}
+{% if <condition> %}
+{% do_something %}
+{% endif %}
+{% endraw %}
+```
+
+```
+{% raw %}
+{% for <item> in <list> %}
+Item: {{ item }}
+{% endfor %}
+{% endraw %}
+```
 
 !!! info "Conditionals"
-    Refer to the django documentation for more information.
+    Refer to the [django template language documentation](https://docs.djangoproject.com/en/dev/ref/templates/language/) for more information.
+
+## Report Types
+
+InvenTree supports the following reporting functionality:
+
+| Report Type | Description |
+| --- | --- |
+| [Test Report](./test.md) | Format results of a test report against for a particular StockItem |
+| [Build Order Report](./build.md) | Format a build order report |
+| [Purchase Order Report](./purchase_order.md) | Format a purchase order report |
+| [Sales Order Report](./sales_order.md) | Format a sales order report |
 
 ## Report Options
 
@@ -69,7 +96,7 @@ A number of global reporting options are available for customizing InvenTree rep
 
 ### Enable Reports
 
-By default, the reporting feature is turned off. It must be enabled in the global settings. 
+By default, the reporting feature is disabled. It must be enabled in the global settings. 
 
 
 ### Default Page Size
@@ -127,6 +154,10 @@ Asset files can be rendered directly into the template as follows
 !!! warning "Asset Naming"
     If the requested asset name does not match the name of an uploaded asset, the template will continue without loading the image.
 
+!!! info "Assets location"
+    You need to ensure your asset images to the report/assets directory in the [data directory](../start/docker_dev.md/#data-directory). Upload new assets via the [admin interface](../settings/admin.md) to ensure they are uploaded to the correct location on the server.
+
+
 ## Report Snippets
 
 A powerful feature provided by the django / WeasyPrint templating framework is the ability to include external template files. This allows commonly used template features to be broken out into separate files and re-used across multiple templates.
@@ -162,7 +193,7 @@ For example, consider a stocktake report for a particular stock location, where
 !!! info "Snippet Arguments"
     Note above that named argument variables can be passed through to the snippet!
 
-And the snippet file `stock_row.html` is as follows:
+And the snippet file `stock_row.html` may be written as follows:
 
 ```html
 {% raw %}
@@ -173,31 +204,3 @@ And the snippet file `stock_row.html` is as follows:
 </tr>
 {% endraw %}
 ```
-
-## Report Types
-
-InvenTree supports the following reporting functionality:
-
-### Test Report
-
-[Test Report](./test.md): Format results of a test report against for a particular StockItem
-
-### Packing List
-[Packing List](./pack.md): Format a list of items for shipping or transfer
-
-### Build Report
-
-[Build Order](./build.md): Format a build order report
-
-### Purchase Order
-[Purchase Order report](./order.md): Order line items 
-
-### Sales Order
-
-!!! missing "TODO"
-	This section requires further work
-
-### Stocktake
-
-!!! missing "TODO"
-	This section requires further work

docs/report/sales_order.md

@@ -1,8 +1,8 @@
 ---
-title: Order Report
+title: Sales Order Reports
 ---
 
-## Order Report
+## Sales Order Reports
 
 !!! missing "TODO"
 	This section requires further work

docs/start/config.md

@@ -178,6 +178,9 @@ The logo and custom messages can be changed/set:
 
 If you want to remove the InvenTree branding as far as possible from your end-user also check the [global server settings](../settings/global.md#server-settings). 
 
+!!! info "Custom Logo Path"
+    The provided *custom logo* path must be specified *relative* to the location of thr `/media/` directory.
+
 ## Other Options
 
 ### Middleware

mkdocs.yml

@@ -101,13 +101,15 @@ nav:
     - Shipments: sell/shipment.md
   - Report:
     - Templates: report/report.md
-    - Labels: report/labels.md
     - Reports:
       - Test Reports: report/test.md
       - Packing List: report/pack.md
       - Build Order: report/build.md
-      - Order: report/order.md
+      - Purchase Order: report/purchase_order.md
+      - Sales Order: report/sales_order.md
       - BOM: report/bom.md
+    - Labels: report/labels.md
+    - Media Files: report/media.md
     - Barcodes: report/barcodes.md
     - Context Variables: report/context_variables.md
   - Admin: