diff --git a/docs/README.md b/docs/README.md index 19dfe64610..fc45408342 100644 --- a/docs/README.md +++ b/docs/README.md @@ -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. diff --git a/docs/docs/api/schema.md b/docs/docs/api/schema.md index e964c86804..6c6bead2b2 100644 --- a/docs/docs/api/schema.md +++ b/docs/docs/api/schema.md @@ -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 | diff --git a/docs/docs/plugins/builtin/index.md b/docs/docs/plugins/builtin/overview.md similarity index 100% rename from docs/docs/plugins/builtin/index.md rename to docs/docs/plugins/builtin/overview.md diff --git a/docs/docs/plugins/develop.md b/docs/docs/plugins/develop.md index 4011a17ad1..fc74681860 100644 --- a/docs/docs/plugins/develop.md +++ b/docs/docs/plugins/develop.md @@ -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 | diff --git a/docs/docs/plugins/index.md b/docs/docs/plugins/index.md index c65e49c3cd..416c39f122 100644 --- a/docs/docs/plugins/index.md +++ b/docs/docs/plugins/index.md @@ -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 diff --git a/docs/docs/plugins/metadata.md b/docs/docs/plugins/metadata.md index 762deb9c6e..8bb5513bdb 100644 --- a/docs/docs/plugins/metadata.md +++ b/docs/docs/plugins/metadata.md @@ -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. diff --git a/docs/docs/plugins/mixins/app.md b/docs/docs/plugins/mixins/app.md index 895341d4c6..3cc290c407 100644 --- a/docs/docs/plugins/mixins/app.md +++ b/docs/docs/plugins/mixins/app.md @@ -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 diff --git a/docs/docs/plugins/models.md b/docs/docs/plugins/models.md new file mode 100644 index 0000000000..6a6d8f26dd --- /dev/null +++ b/docs/docs/plugins/models.md @@ -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. diff --git a/docs/extract_schema.py b/docs/extract_schema.py index 2c175a82c7..29444c4b20 100644 --- a/docs/extract_schema.py +++ b/docs/extract_schema.py @@ -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) diff --git a/docs/mkdocs.yml b/docs/mkdocs.yml index edc9388765..09f3c01cac 100644 --- a/docs/mkdocs.yml +++ b/docs/mkdocs.yml @@ -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