feat(docs): preperation for plugin modeling documentation (#13077)

* update descriptions

* add subsections

* another section

* keep nultin seperate

* rename

* make readme easier to copy

* add a seperate overview section like machines

* update generated schema page

* add missing key

* make initial paragraph more objective

* add model doc stump

* fix typos

* fix caps

* adjust readme for easier copy paste

* update generate step

* remove additional doc item
This commit is contained in:
Matthias Mair authored and GitHub committed 2026-11-15 08:50:33 +11:00
1 parent 9e78e73a7c
commit f4f5caae2c
10 files changed
+119 -76

No files matched your search

+14 -14
View File
@@ -23,9 +23,9 @@ InvenTree uses [Zensical](https://zensical.org/) to convert [Markdown](https://z
To build the documentation locally, run these commands as the `inventree` user:
```
$ cd /home/inventree
$ source env/bin/activate
```bash
cd /home/inventree
source env/bin/activate
```
!!! info "(env) prefix"
@@ -33,9 +33,9 @@ $ source env/bin/activate
You can now install the additional packages needed to build the documentation:
```
$ cd src
$ pip install --require-hashes -r docs/requirements.txt
```bash
cd src
pip install --require-hashes -r docs/requirements.txt
```
## Schema generation
@@ -45,8 +45,8 @@ Building the documentation requires extracting the API schema (and settings defi
!!! tip
This command is only required when building the documentation for the first time, or when changes have been made to the API schema.
```
$ invoke build-docs
```bash
invoke build-docs
```
You will see output similar to this (truncated for brevity):
@@ -67,24 +67,24 @@ Documentation build complete, but zensical build not requested
To generate the schema files *and* build the static HTML site (in `docs/site/`), including the post-build checks that all settings are documented, run:
```
$ invoke build-docs --build
```bash
invoke build-docs --build
```
## Viewing the documentation
Generate the HTML files from the markdown source files, and start the zensical webpage server:
```
$ zensical serve -a localhost:8080 -f docs/mkdocs.yml
```bash
zensical serve -a localhost:8080 -f docs/mkdocs.yml
```
You can then point your web browser at http://localhost:8080/
Alternatively, you can use the `invoke` command:
```
$ invoke dev.docs-server
```bash
invoke dev.docs-server
```
If you need to, use the `-a` option after `zensical serve` or `invoke` to set the address and port. Run `invoke dev.docs-server --help` for details.
+3 -2
View File
@@ -9,7 +9,7 @@ The API schema as documented below is generated using the [drf-spectactular](htt
## API Version
This documentation is for API version: `578`
This documentation is for API version: `579`
!!! tip "API Schema History"
We track API schema changes, and provide a snapshot of each API schema version in the [API schema repository](https://github.com/inventree/schema/).
@@ -30,12 +30,13 @@ API schema documentation is split into the following categories:
| [Bill of Materials](./schema/bom.md) | Bill of Materials |
| [Build Order Management](./schema/build.md) | Build Order Management |
| [Company Management](./schema/company.md) | Company Management |
| [Data Importing](./schema/importer.md) | Data Importing |
| [Label Printing](./schema/label.md) | Label Printing |
| [External Machine Management](./schema/machine.md) | External Machine Management |
| [External Order Management](./schema/order.md) | External Order Management |
| [Parts and Part Categories](./schema/part.md) | Parts and Part Categories |
| [Plugin Functionality](./schema/plugins.md) | Plugin Functionality |
| [Part Pricing](./schema/pricing.md) | Part Pricing |
| [Part and Stock Pricing](./schema/pricing.md) | Part and Stock Pricing |
| [Report Generation](./schema/report.md) | Report Generation |
| [Settings Management](./schema/settings.md) | Settings Management |
| [Stock and Stock Locations](./schema/stock.md) | Stock and Stock Locations |
File renamed without changes.
+13 -13
View File
@@ -43,7 +43,7 @@ from plugin.mixins import APICallMixin, SettingsMixin, ScheduleMixin, BarcodeMix
```
- Deliver as a package (see [below](#packaging))
- If you need to use a private infrastructure, use the 'Releases' functions in GitHub or Gitlab. Point to the 'latest' release endpoint when installing to make sure the update function works
- Tag your GitHub repo with `inventree` and `inventreeplugins` to make discovery easier. A discovery mechanism using these tags is on the roadmap.
- Tag your GitHub repo with `inventree` and `inventreeplugins` to make discovery easier.
- Use GitHub actions to test your plugin regularly (you can [schedule actions](https://docs.github.com/en/actions/learn-github-actions/events-that-trigger-workflows#schedule)) against the 'latest' [docker-build](https://hub.docker.com/r/inventree/inventree) of InvenTree
- If you use the AppMixin pin your plugin against the stable branch of InvenTree, your migrations might get messed up otherwise
@@ -126,25 +126,25 @@ Supported mixin classes are:
| Mixin | Description |
| --- | --- |
| [ActionMixin](./mixins/action.md) | Run custom actions |
| [ActionMixin](./mixins/action.md) | Run custom actions triggered via a HTTP endpoint |
| [AllocateMixin](./mixins/allocate.md) | Customize automatic stock allocation |
| [APICallMixin](./mixins/api.md) | Perform calls to external APIs |
| [AppMixin](./mixins/app.md) | Integrate additional database tables |
| [APICallMixin](./mixins/api.md) | Perform calls to external APIs respecting built-in safety mechanism |
| [AppMixin](./mixins/app.md) | Add models (database tables) and complex django logic |
| [BarcodeMixin](./mixins/barcode.md) | Support custom barcode actions |
| [CurrencyExchangeMixin](./mixins/currency.md) | Custom interfaces for currency exchange rates |
| [DataExport](./mixins/export.md) | Customize data export functionality |
| [EventMixin](./mixins/event.md) | Respond to events |
| [LabelPrintingMixin](./mixins/label.md) | Custom label printing support |
| [LocateMixin](./mixins/locate.md) | Locate and identify stock items |
| [EventMixin](./mixins/event.md) | Respond to events within the platform |
| [LabelPrintingMixin](./mixins/label.md) | Customize label printing control flow and operations |
| [LocateMixin](./mixins/locate.md) | React to locate events on stock and customize handling |
| [MachineDriverMixin](./mixins/machine.md) | Integrate custom machine drivers
| [MailMixin](./mixins/mail.md) | Send custom emails |
| [MailMixin](./mixins/mail.md) | Customize email handling (incoming and outgoing) |
| [NavigationMixin](./mixins/navigation.md) | Add custom pages to the web interface |
| [NotificationMixin](./mixins/notification.md) | Send custom notifications in response to system events |
| [ReportMixin](./mixins/report.md) | Add custom context data to reports |
| [NotificationMixin](./mixins/notification.md) | Add custom ways to deliver notifications to users |
| [ReportMixin](./mixins/report.md) | Expose custom context data to reports and labels on generation |
| [ScheduleMixin](./mixins/schedule.md) | Schedule periodic tasks |
| [SettingsMixin](./mixins/settings.md) | Integrate user configurable settings |
| [UserInterfaceMixin](./mixins/ui.md) | Add custom user interface features |
| [UrlsMixin](./mixins/urls.md) | Respond to custom URL endpoints |
| [SettingsMixin](./mixins/settings.md) | Define configurable settings (for system or user) for your plugin |
| [UserInterfaceMixin](./mixins/ui.md) | Customize the web interface (add pages, actions, panels, navigation items, ...) |
| [UrlsMixin](./mixins/urls.md) | Add to custom URL endpoints / views |
| [ValidationMixin](./mixins/validation.md) | Provide custom validation of database models |
| [WellKnownMixin](./mixins/wellknown.md) | Provide well-known endpoints on the root of an instance |
+2 -2
View File
@@ -10,7 +10,7 @@ Plugins can be added from multiple sources:
- Plugins can be installed using the PIP Python package manager
- Plugins can be placed in the external [plugins directory](../start/config.md#plugin-options)
- InvenTree [built-in](./builtin/index.md) plugins are located within the InvenTree source code
- InvenTree [built-in](./builtin/overview.md) plugins are located within the InvenTree source code
For further information, read more about [installing plugins](./install.md).
@@ -38,7 +38,7 @@ InvenTree plugins can be provided from a variety of sources, including built-in
InvenTree comes with a number of built-in plugins that provide additional functionality. These plugins are included in the InvenTree source code, and can be enabled or disabled via the configuration options.
Refer to the [built-in plugins documentation](./builtin/index.md) for more information on the available built-in plugins.
Refer to the [built-in plugins documentation](./builtin/overview.md) for more information on the available built-in plugins.
### Sample Plugins
+6 -4
View File
@@ -4,11 +4,13 @@ title: Model Metadata
## Model Metadata
Plugins have access to internal database models (such at [Parts](../part/index.md)), and any associated data associated with these models. It may be the case that a particular plugin needs to store some extra information about a particular model instance, to be able to perform custom functionality.
Plugins can access internal database models, such as [Parts](../part/index.md), and their associated data. A plugin may need to store additional information for a specific model instance.
One way of achieving this would be to create an entirely new database model to keep track of this information, using the [app plugin mixin](./mixins/app.md). However, this is a very heavy-handed (and complicated) approach!
One option is to define a [database model](./models.md) using the [app plugin mixin](./mixins/app.md). This requires some knowledge of Django models and database design.
A much simpler and more accessible method of recording custom information against a given model instance is provided "out of the box" - using *Model Metadata*.
For information that can be represented as JSON, *Model Metadata* provides a way to store data on supported model instances without defining a separate model or handling lifecycle considerations.
This page describes how to use the model metadata mechanism.
### MetadataMixin Class
@@ -122,4 +124,4 @@ There is no guarantee that the data added to a particular model will *not* be ov
### Structured Data
If you need to store data which is more "structured" than JSON objects, consider using the (more complex) [app mixin](./mixins/app.md) to develop custom database tables for your data.
If you need to store data which is more "structured" than JSON objects, consider using the (more involved) [app mixin](./mixins/app.md) to develop custom database tables for your data.
+2 -2
View File
@@ -6,12 +6,12 @@ title: App Mixin
If this mixin is added to a plugin the directory the plugin class is defined in is added to the list of `INSTALLED_APPS` in the InvenTree server configuration.
!!! warning "Danger Zone"
!!! warning "Expert Mode"
Only use this mixin if you have an understanding of Django's [app system]({% include "django.html" %}/ref/applications). Plugins with this mixin are deeply integrated into InvenTree and can cause difficult to reproduce or long-running errors. Use the built-in testing functions of Django to make sure your code does not cause unwanted behaviour in InvenTree before releasing.
## Custom Models
This mixin allows you to define custom database models within your plugin. These models will be automatically registered with the InvenTree server, and will be available for use within your plugin code.
This mixin allows you to define [custom database models](../models.md) within your plugin. These models will be automatically registered with the InvenTree server, and will be available for use within your plugin code.
### Model Permissions
+36
View File
@@ -0,0 +1,36 @@
---
title: Defining Models
---
[App Mixins](./mixins/app.md) allow the usage of most Django features - amongst the most important use cases is the ability to freely design custom database models for a plugin. While almost all Django model features are supported, it is beneficial to use the built-in abstractions and generic features provided by InvenTree as those are well supported by the platform and come with good API integration.
## The apps module
The `apps` module in a plugin defines the general configuration of the registered Django app and its models.
A typical `apps.py` file in a plugin might look like this:
```python
from django.apps import AppConfig
class MyPluginConfig(AppConfig):
default_auto_field = 'django.db.models.BigAutoField'
name = 'my_plugin' # this is important for Django to identify the app correctly, ensure this name does not change once users have installed the plugin
label = 'my_plugin'
```
This configuration ensures that Django recognizes the plugin as a valid application and allows it to integrate seamlessly with the InvenTree server. Adding any code in the AppConfig should be carefully considered as it can introduce significant startup overhead.
## Base classes
A typical Django model class is based on `django.db.models.Model`, which provides the core functionality for defining database models in Django. Alternatively, `InvenTree.models.InvenTreeModel` comes with a few additional core integrations (content type association, [plugin validation](./mixins/validation.md)) or `InvenTree.models.InvenTreeMetadataModel` which also includes [model metadata](./metadata.md) support for the model instances.
## Generic Model Mixins
### MetadataMixin
Adds support for [model metadata](./metadata.md) support, allowing additional information to be attached to model instances. This metadata can be accessed and manipulated through the InvenTree API or by other plugins.
### InvenTreeParameterMixin
Adds support for [parameters](../concepts/parameters.md), allowing your models to use the parameter mechanism including proper permission checks and integration with the InvenTree API.
+2 -2
View File
@@ -80,6 +80,8 @@ def generate_index_file(version: str):
title: InvenTree API Schema
---
## InvenTree API Schema
The InvenTree API is implemented using the [Django REST framework](https://www.django-rest-framework.org).
The API schema as documented below is generated using the [drf-spectactular](https://github.com/tfranzel/drf-spectacular/) extension.
@@ -109,8 +111,6 @@ def generate_index_file(version: str):
output += '| [General](./schema/general.md) | General API endpoints |\n'
output += '\n'
output_file = os.path.join(os.path.dirname(__file__), OUTPUT_DIR, '..', 'schema.md')
print('Writing index file to:', output_file)
+41 -37
View File
@@ -218,43 +218,47 @@ nav:
- Plugins:
- Overview: plugins/index.md
- Installation: plugins/install.md
- Developing a Plugin: plugins/develop.md
- Frontend Integration: plugins/frontend.md
- Plugin Creator: plugins/creator.md
- Plugin Walkthrough: plugins/walkthrough.md
- Model Metadata: plugins/metadata.md
- Tags: plugins/tags.md
- Unit Test: plugins/test.md
- Plugin Mixins:
- Action Mixin: plugins/mixins/action.md
- Allocate Mixin: plugins/mixins/allocate.md
- API Mixin: plugins/mixins/api.md
- App Mixin: plugins/mixins/app.md
- Barcode Mixin: plugins/mixins/barcode.md
- Currency Mixin: plugins/mixins/currency.md
- Event Mixin: plugins/mixins/event.md
- Data Export Mixin: plugins/mixins/export.md
- Icon Pack Mixin: plugins/mixins/icon.md
- Label Printing Mixin: plugins/mixins/label.md
- Locate Mixin: plugins/mixins/locate.md
- Machine Mixin: plugins/mixins/machine.md
- Mail Mixin: plugins/mixins/mail.md
- Navigation Mixin: plugins/mixins/navigation.md
- Notification Mixin: plugins/mixins/notification.md
- Report Mixin: plugins/mixins/report.md
- Schedule Mixin: plugins/mixins/schedule.md
- Settings Mixin: plugins/mixins/settings.md
- Supplier Mixin: plugins/mixins/supplier.md
- Transition Mixin: plugins/mixins/transition.md
- URL Mixin: plugins/mixins/urls.md
- User Interface Mixin: plugins/mixins/ui.md
- Validation Mixin: plugins/mixins/validation.md
- Well-Known Mixin: plugins/mixins/wellknown.md
- Machines:
- Overview: plugins/machines/overview.md
- Label Printer: plugins/machines/label_printer.md
- Builtin:
- Builtin Plugins: plugins/builtin/index.md
- Tutorials:
- Developing a Plugin: plugins/develop.md
- Frontend Integration: plugins/frontend.md
- Plugin Creator: plugins/creator.md
- Step-by-Step Walkthrough: plugins/walkthrough.md
- Guides:
- Model Metadata: plugins/metadata.md
- Defining Models: plugins/models.md
- Tags: plugins/tags.md
- Unit Test: plugins/test.md
- References:
- Plugin Mixins:
- Action Mixin: plugins/mixins/action.md
- Allocate Mixin: plugins/mixins/allocate.md
- API Mixin: plugins/mixins/api.md
- App Mixin: plugins/mixins/app.md
- Barcode Mixin: plugins/mixins/barcode.md
- Currency Mixin: plugins/mixins/currency.md
- Event Mixin: plugins/mixins/event.md
- Data Export Mixin: plugins/mixins/export.md
- Icon Pack Mixin: plugins/mixins/icon.md
- Label Printing Mixin: plugins/mixins/label.md
- Locate Mixin: plugins/mixins/locate.md
- Machine Mixin: plugins/mixins/machine.md
- Mail Mixin: plugins/mixins/mail.md
- Navigation Mixin: plugins/mixins/navigation.md
- Notification Mixin: plugins/mixins/notification.md
- Report Mixin: plugins/mixins/report.md
- Schedule Mixin: plugins/mixins/schedule.md
- Settings Mixin: plugins/mixins/settings.md
- Supplier Mixin: plugins/mixins/supplier.md
- Transition Mixin: plugins/mixins/transition.md
- URL Mixin: plugins/mixins/urls.md
- User Interface Mixin: plugins/mixins/ui.md
- Validation Mixin: plugins/mixins/validation.md
- Well-Known Mixin: plugins/mixins/wellknown.md
- Machines:
- Overview: plugins/machines/overview.md
- Label Printer: plugins/machines/label_printer.md
- Builtin Plugins:
- Overview: plugins/builtin/overview.md
- Barcode Plugins:
- Barcode Plugins: plugins/builtin/barcode_index.md
- InvenTree Barcode: plugins/builtin/inventree_barcode.md